Calling a secured API from a browser client application or native apps.
This flow (implicit grant) is used for JavaScript clients and native apps on mobile devices. This flow is initiated by a request for an access token using an HTTP GET on the authorization endpoint of the Authorization Server. In this request the client asks to access an API on behalf of the user (resource owner).
The Authorization Server will upon receiving the request, redirect to a page to allow the resource owner to authenticate and grant permission to the client to call the API on his behalf.
If the resource owner granted permission to the client, the Authorization Server will redirect to the redirection uri specified by the client. The access token will be provided via the fragment of the redirection uri.
GET ws/oauth/v2/authorization/
| Endpoint | Description | Method |
|---|---|---|
| https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/authorization | This endpoint is the target of the initial request for an access token. | HTTP-GET |
The query string is composed of the following parameters.
| Parameter | Values | Description | Required |
|---|---|---|---|
response_type |
token | Value MUST be set to "token". | Yes |
client_id |
The client id obtained via the OAuth administration site. | The client identifier is a unique string representing the registration information provided by the client. | Yes |
redirect_uri |
One of the redirect uri values for the specified client, registered at the OAuth administration site. | The value must exactly match the registered value, including case and trailing '/' | Yes |
scope |
Space delimited set of scopes the client requests. | One or more of the scope values available for the specified client. See the OAuth administration site for available scopes. Multiple scopes must be space seperated. | No (if a default scope is defined for the specified client, otherwise Yes) |
state |
Any string | An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery. | No (but recommended) |
Example
GET https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/authorization?response_type=token&client_id=789456&redirect_uri=https%3A%2F%2Fmysite.com%2Fcallbackoauth&scope=KlipRead&state=m0==788ZZz HTTP/1.1
Handling the response
The OAuth 2.0 Authorization Server returns an access token to the client if the resource owner grants the client one or more of the scopes the client requested. The url fragment is composed of the following parameters.| Parameter | Values | Description |
|---|---|---|
access_token (fragment) |
A string representing the access token issued by the OAuth 2.0 Authorization Server | The access token issued by the OAuth 2.0 Authorization Server |
token_type |
bearer | The access token is a bearer token. |
expires_in |
A numeric value | The lifetime of the access token in seconds starting from the time the token was issued. |
scope |
Space delimited set of scopes the resource owner granted the client. | The scopes specified can be different from the requested scopes when the resource owner doesn't or can't grant all of the requested scopes. |
state |
Any string | The exact value of the state parameter that was specified when requesting an access token. If no state parameter was passed when requesting the access token, this parameter is not present in the response. |
Example
https://mysite.com/callbackoauth#access_token=LTgaAik7F-smmQ65_nVfag==&token_type=bearer&expires_in=599&scope=KlipRead&state=m0==788ZZz
Handling an error
The OAuth 2.0 Authorization Server returns an error when to the client if the resource owner doesn't grant the client any of the requested scopes or when the specified parameters are invalid.When the specified client_id or redirect_uri parameter in the access token request is invalid, the user agent is not redirected to the specified redirect_uri. Instead a message is displayed informing the resource owner.
| Parameter | Values | Description |
|---|---|---|
error (fragment) |
access_denied |
The resource owner or the OAuth 2.0 Authorization Server denied the request. |
unsupported_response_type |
The OAuth 2.0 Authorization Server does not support obtaining an access token of the specified type using this method. | |
server_error |
The OAuth 2.0 Authorization Server encountered an unexpected condition that prevented it from fulfilling the request. | |
invalid_scope |
The requested scope is invalid, unknown, or malformed. | |
unauthorized_client |
The client is not authorized to request an access token using this method. | |
state |
Any string | The exact value of the state parameter that was specified when requesting an access token. If no state parameter was passed when requesting the access token, this parameters is not present in the response. |
Example
https://mysite.com/callbackoauth#error=access_denied&state=m0==788ZZzCalling an API
When your application has received an access token, you can access an API by including the access token in the Authorization HTTP Header using the Bearer scheme.
For example a call to an API using the access_token Authorization: Bearer HTTP header looks as follows:
GET https://api.vlaanderen.be/ws/klip/v1/maprequest HTTP/1.1
Authorization: Bearer LTgaAik7F-smmQ65_nVfag==
Host: api.agiv.be
When HTTP Header operations are not possible, for example when using the url in an image src attribute, the access token can be incuded as a query string parameter.
For example, a call to the API using the access_token query string parameter looks like the following:
GET https://api.vlaanderen.be/ws/klip/v1/maprequest?access_token=LTgaAik7F-smmQ65_nVfag== HTTP/1.1