Authorization API documentation

Using OAuth 2.0 for B2B with the client credentials grant

This flow (Client Credentials 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, and where the resource owner of the API is the same as the client itself. If you are not writing your client for your own organisation then you should look at the B2B with authorization code 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 with the client credentials grant

Obtaining the client

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

To register a B2B client we need the following information:

  • A descriptive name of your client.
  • A contact with a valid Informatie Vlaanderen account. You can register at https://beta.oauth.vlaanderen.be
  • The scopes your client needs, to access the API (consult the documentation of the API)
  • Your scenario that you chose, in this case Client Credentials Grant

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:

  • upload a JSON Web Key for client authentication
  • upload a certificate for client authentication that will be wrapped in a JSON Web Key
  • obtain the client id and client secret.
  • regenerate the client secret.
  • Invalidate the tokens

Overview Flow

Step 1

The client authenticates with the authorization server and requests an access token from the token endpoint at https://beta.oauth.vlaanderen.be/ws/oauth/v2/token/


Step 2

The client receives an access token response

Obtaining access tokens

After you have the client ID and client secret or JSON Web Key, you can send an HTTP POST to the OAuth 2.0 token endpoint at https://beta.oauth.vlaanderen.be/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 client_credentials Value MUST be set to "client_credentials". Yes
scope The scope of the access request. 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)

Client Authentication values

You also need to authenticate the client, 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=client_credentials
&scope=MapRequestInitiator
&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=client_credentials
&scope=MapRequestInitiator


The body only contains extra newlines for readability. Be sure to url-encode the clientId and the clientsecret before encoding it in base64.

Handling the response

The OAuth 2.0 Authorization Server returns an access token to the client if it successfully authenticates the client. 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.

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    
}

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

Access tokens have a limited lifetime. The client should cache the access token for the validity of the token, and only request a new token when this access token is expired. Throttling may apply if too many requests for the same clientId reaches the OAuth 2.0 authorization server.

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 invalid_client Client authentication failed
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_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