Authorization API documentation

Calling a secured API from a web server application

This flow (Authorization Code Grant) is used in scenarios where a web server needs to make secured calls to an API, even when the user is offline. It can only be used by confidential clients who are in possession of a client secret.

This flow is initiated by a client application which sends an HTTP GET request for an authorization code to the Authorization Server. The Authorization Server will redirect the user to a page to authenticate himself and grant permission to the client to call the API. After the user has given his consent, the Authorization Server redirects to the client redirection uri and passes an authorization code as a query string.

The client (web server application) can now use the authorization code to exchange it for an access token and use the received token to call the API. In the response the client also receives a refresh token that can be used to request a new access token when the current access token is about to expire. These flows can be done by the webserver without interaction of the user.


Implicit Grant Sequence Diagram

Requesting an authorization code from the authorization server.

The endpoint used to request an OAuth 2.0 Authorization code is https://beta.oauth.vlaanderen.be/authorization/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 code Value MUST be set to "code". 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=code&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 authorization code to the client if the resource owner grants the client one or more of the scopes the client requested. The query string is composed of the following parameters.

Parameter Values Description
code A string representing the authorization code issued by the OAuth 2.0 Authorization Server The authorization code issued by the OAuth 2.0 Authorization Server
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


GET https://mysite.com/callbackoauth?code=5fFiTSTWXCQwGx6lSmJHQ&state=m0788ZZz HTTP/1.1
    

Handling an error

The OAuth 2.0 Authorization Server returns an error 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==788ZZz

Exchanging the authorization code for an access token.

The endpoint used to exchange an authorization code for an access token is https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token/

Endpoint Description Method
https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ This endpoint is the target of the initial request to exchange an authorization code for an access token. HTTP-POST

The body is composed of the following parameters.

Parameter Values Description Required
grant_type authorization_code Value MUST be set to "authorization_code". Yes
redirect_uri The redirect uri value used in the authorization code request. The value must exactly match the previously used and registered value, including case and trailing '/' Yes
code The authorization code. The authorization code obtained by the client using a authorization code grant request. Yes

Client Authentication

You also need to authenticate the client for this call, you can find information in client authentication

The client authentication methods that are allowed are:

If you use a JSON Web Token the audience for this call in the JWT token must be:

  • https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token

Examples


POST https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: beta.oauth.vlaanderen.be
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=5fFiTSTWXCQwGx6lSmJHQ
&redirect_uri=https%3A%2F%2Fmysite.com%2Fcallbackoauth
&client_id=789456
&client_secret=298MSGHSJY93273253GIDGIDZN_VCX2H3


POST https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: beta.oauth.vlaanderen.be
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=5fFiTSTWXCQwGx6lSmJHQ
&redirect_uri=https%3A%2F%2Fmysite.com%2Fcallbackoauth
&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imo5c1ZrNU9INVlOQS1uMS00bDdUM013UVJJUSJ9.eyJzdWIiOiI3ODk0NTYiLCJpc3MiOiI3ODk0NTYiLCJleHAiOiIxNTE2MjQwMDIyIiwiaWF0IjoiMTU1MjkwOTYwMSIsImp0aSI6IjYzMjMzY2Q5LTIxYjgtNGZhMS04ODU4LTY2YjcxNWY3YTg2NiIsImF1ZCI6Imh0dHBzOi8vb2F1dGgudmxhYW5kZXJlbi5iZS9hdXRob3JpemF0aW9uL3dzL29hdXRoL3YyL2F1dGhvcml6YXRpb24ifQ.dPWB45Fe-ctNq5Q5bwGSVfFjbVoGMd6mrKzd3V9Xaq136vnAABYstr9v0E-rTz_VjoHJOpS23336-3ooDEl-bahfVJhpsjTW2_8X8eU9Jdyznl5VWpLKfAmHW9ycWupMf3jeCGfbLe5e1Nj1AmMuvufwawpb8-c9XuRoJoK6y232gRa-xfBQxJMcaS8L9qxYVLecPeqQjnjAs0qDOzrRzyIDLC9fBUG0UeC4sd_rEMSgBSj_N5uMbg4hyV6HB6-WuJy0R_MWFRq_fgqa3vRqDd9D0epLc-_QugfeGgdryKer57WLtbYfDXWoXEgsKmqToHyZx2G96ohuIqws3ytxxg
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer


POST https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: beta.oauth.vlaanderen.be
Authorization: Basic Nzg5NDU2OjI5OE1TR0hTSlk5MzI3MzI1M0dJREdJRFpOX1ZDWDJIJTNEJTNE
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=5fFiTSTWXCQwGx6lSmJHQ    
&redirect_uri=https%3A%2F%2Fmysite.com%2Fcallbackoauth


The body only contains extra newlines for readability. Be sure to url-encode code, clientsecret, client_assertion, client_assertion_type and redirect uri.

Handling the response

The OAuth 2.0 Authorization Server returns an access token to the client if it successfully authenticates the client, and the authorization code and redirect uri are valid. The body of the response is a json result.

Property Values Description
access_token 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
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.
refresh_token A string representing a refresh token that can be used to request a new access token. The refresh token issued by the OAuth 2.0 Authorization Server

Example


HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"MOB1ZkyrqdSay4-xm39Z6A==",
    "scope":"KlipRead",
    "expires_in":3600,
    "refresh_token":"IW0fZn_GGwLTnoMfH9ug=="
}

Handling an error

The OAuth 2.0 Authorization Server returns an error as a json result to the client if the request parameters are not correct or an access token could not be issued.

Property Value Description
error access_denied The resource owner or the OAuth 2.0 Authorization Server denied the request.
unsupported_grant_type The OAuth 2.0 Authorization Server does not support obtaining an access token of the specified grant type using this method.
invalid_grant The provided authorization code, refresh token or assertion is invalid, revoked expired, or the redirect uri used, was not the redirect uri used in the initial authorization 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.
invalid_request The request is missing required parameters or is malformed.
error_description Descriptive text to provide additional information about the error.

Example


HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
    
{ 
    "error":"invalid_request" 
}

Calling 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

Exchanging a refresh token for an access token.

The endpoint used to exchange a refresh token for an access token is https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token/

Endpoint Description Method
https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ This endpoint is the target of the initial request to exchange an authorization code for an access token. HTTP-POST

The body is composed of the following parameters.

Parameter Values Description Required
grant_type refresh_token Value MUST be set to "refresh_token". Yes
refresh_token The refresh token. The refresh token obtained by the client (web server) by exchanging an authorization code or refresh token via a previous request. Yes

Client Authentication

You also need to authenticate the client for this call, you can find information in client authentication

The client authentication methods that are allowed are:

If you use a JSON Web Token the audience for this call in the JWT token must be:

  • https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token

Examples


POST https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: beta.oauth.vlaanderen.be
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=5fFiTSTWXCQwGx6lSmJHQ
&client_id=789456
&client_secret=298MSGHSJY93273253GIDGIDZN_VCX2H3


POST https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: beta.oauth.vlaanderen.be
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=5fFiTSTWXCQwGx6lSmJHQ
&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imo5c1ZrNU9INVlOQS1uMS00bDdUM013UVJJUSJ9.eyJzdWIiOiI3ODk0NTYiLCJpc3MiOiI3ODk0NTYiLCJleHAiOiIxNTE2MjQwMDIyIiwiaWF0IjoiMTU1MjkwOTYwMSIsImp0aSI6IjYzMjMzY2Q5LTIxYjgtNGZhMS04ODU4LTY2YjcxNWY3YTg2NiIsImF1ZCI6Imh0dHBzOi8vb2F1dGgudmxhYW5kZXJlbi5iZS9hdXRob3JpemF0aW9uL3dzL29hdXRoL3YyL2F1dGhvcml6YXRpb24ifQ.dPWB45Fe-ctNq5Q5bwGSVfFjbVoGMd6mrKzd3V9Xaq136vnAABYstr9v0E-rTz_VjoHJOpS23336-3ooDEl-bahfVJhpsjTW2_8X8eU9Jdyznl5VWpLKfAmHW9ycWupMf3jeCGfbLe5e1Nj1AmMuvufwawpb8-c9XuRoJoK6y232gRa-xfBQxJMcaS8L9qxYVLecPeqQjnjAs0qDOzrRzyIDLC9fBUG0UeC4sd_rEMSgBSj_N5uMbg4hyV6HB6-WuJy0R_MWFRq_fgqa3vRqDd9D0epLc-_QugfeGgdryKer57WLtbYfDXWoXEgsKmqToHyZx2G96ohuIqws3ytxxg
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer


POST https://beta.oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: beta.oauth.vlaanderen.be
Authorization: Basic Nzg5NDU2OjI5OE1TR0hTSlk5MzI3MzI1M0dJREdJRFpOX1ZDWDJIJTNEJTNE
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=5fFiTSTWXCQwGx6lSmJHQ


The body only contains extra newlines for readability. Be sure to url-encode the clientsecret and refresh_token.

Handling the response

The OAuth 2.0 Authorization Server returns an access token to the client if it successfully authenticates the client, and the authorization code and redirect uri are valid. The body of the response is a json result.

Property Values Description
access_token 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
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.
expires_in A numeric value The lifetime of the access token in seconds starting from the time the token was issued.
refresh_token A string representing a refresh token that can be used to request a new access token. The refresh token issued by the OAuth 2.0 Authorization Server

Example


HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"MOB1ZkyrqdSay4-xm39Z6A==",
    "scope":"KlipRead",
    "expires_in":3600,
    "refresh_token":"IW0fZn_GGwLTnoMfH9ug=="
}

Handling an error

The OAuth 2.0 Authorization Server returns an error as a json result to the client if the request parameters are not correct or an access token could not be issued.

Property Value Description
error access_denied The resource owner or the OAuth 2.0 Authorization Server denied the request.
unsupported_grant_type The OAuth 2.0 Authorization Server does not support obtaining an access token of the specified grant type using this method.
invalid_grant The provided authorization code, refresh token or assertion is invalid, revoked expired, or the redirect uri used, was not the redirect uri used in the initial authorization 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.
invalid_request The request is missing required parameters or is malformed.
error_description Descriptive text to provide additional information about the error.

Example


HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
    
{ 
    "error":"invalid_request" 
}