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.
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:
- With a JSON Web Key
- With the client identifier and client secret in the header
- With the client identifier and client secret in the body
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:
- With a JSON Web Key
- With the client identifier and client secret in the header
- With the client identifier and client secret in the body
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"
}