Authorization API documentation

Content

Introduction

Calling a secured API from browser applications and native apps
Calling a secured API from web server applications
Calling a secured API from a server using OAuth 2.0 Token Exchange

Calling a secured API from a server (B2B) with authorization code grant
Calling a secured API from a server (B2B) with the client credentials grant
Calling a secured API from a server (B2B) using a SAML 1.1 Assertion.

Requesting the profile information of the Resource Owner of an OAuth 2.0 Access Token
Revoking tokens

Verifying an OAuth 2.0 Access Token as a Resource Server

Using OAuth 2.0 for B2B with authorization code grant

This flow (Authorization Code Grant) is used in scenarios where a server needs to make secured calls to an API, without user interaction or consent. It can only be used by confidential clients who are in possession of a client secret. It is optimal for clients who have a lot of customers who want to access the API. If the owner of the client is in the same organisation as the one making the API call you should take a look at the Client Credentials grant scenario.

In B2B scenario’s, for example batch applications, these processes do not have the interactive capabilities to ask consent of the user to access an API on behalf of the user. This document describes how you can obtain OAUth2.0 access tokens to an API in a B2B scenario

Overview

Step 1: Obtaining an Authorization Code (Interactive step)

This flow starts with an interactive step. The contact of the client logs into the OAuth Client Admin site to request an Authorization Code for a specific Service Account.


Step 2: Exchange the Authorization Code for an Access Token

When the client process starts, it sends a request to the token endpoint with a set of parameters and the initial authorization code. The response includes an access token, a refresh token and an access token expiration.


Step 3: Exchange a Refresh Token for an Access Token

Once the Access Token is no longer valid, the client process sends a request to the token endpoint to exchange the previously obtained Refresh Token for a new Access Token and Refresh Token.

Obtaining the initial authorization code

As in all OAuth 2.0 scenarios, you will first need to register your client with Digitaal Vlaanderen. In order to register your client contact the Digitaal Vlaanderen Security team.

To register a B2B client we need the following information:

  • A descriptive name of your client.
  • A contact with a valid geosecure account.
  • The scopes your client needs, to access the API (consult the documentation of the API)
  • The service account(s) on behalf of which your client will access the API.

After successful registration the contact will receive an e-mail containing a link to a page to manage his registered client(s).

On this page the contact can:

  • obtain the client id and client secret.
  • regenerate the client secret.
  • upload a JSON Web Key and use that as clientsecret
  • upload a certificate and use that as a client secret wrapped in a JSON Web Key
  • generate an initial authorization code for a service account.

Obtaining access tokens and refresh tokens

After you have the client ID and client secret, you can send an HTTP POST to the OAuth 2.0 token endpoint at https://https://oauth.vlaanderen.be/authorization//ws/oauth/v2/token/ with your client id, client secret, authorization code and redirection uri configured in your registration page.

Endpoint Description Method
https://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 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://oauth.vlaanderen.be/authorization/ws/oauth/v2/token

Examples 


POST https://oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: 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%3D%3D
    



POST https://oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: 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://oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: 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 the code, clientsecret, clientassertion, clientassertiontype 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
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.
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==",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"IW0fZn_GGwLTnoMfH9ug=="
}

Upon receipt of this response, your application may use the access token in API requests.

Access tokens have a limited lifetime. If your application needs access to an API over a long period of time, then it can use the refresh token to obtain a new access token. If your application needs this type of access, then it should store the refresh tokens securely in long-term storage for later use.

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.

You can use the refresh token to request a new access token. Once the refresh token has been exchanged your receive a new access token and refresh token. The previous refresh token will still be valid for a period of 1 hour to handle the following situations:

  • The response containing the new access token and refresh token never reaches your process or times out. In this case your process retry logic can request a new access token using the previous refresh token.
  • Your system is an asynchronous or multi-threaded process. In that case multiple threads or processes could have cached the refresh token and ask for a new access token at different points in time.

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

Endpoint Description Method
https://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://oauth.vlaanderen.be/authorization/ws/oauth/v2/token

Examples 


POST https://oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: 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://oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: 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://oauth.vlaanderen.be/authorization/ws/oauth/v2/token/ HTTP/1.1
Host: 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 refreshtoken, clientsecret, clientassertion and the clientassertion type

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
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.
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==",
    "token_type":"bearer",
    "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" 
}
© 2024 Digitaal Vlaanderen - Alle rechten voorbehouden - Havenlaan 88, 1000 Brussel | Koningin Maria Hendrikaplein 70, 9000 Gent - E digitaal.vlaanderen@vlaanderen.be