Requesting An Access Token
Access tokens can be obtained using one of the standardized OAuth 2.0 flows. Currently two flows are supported: The Implicit Flow and the Client Credentials flow. Additional flows may be added, depending on our customer’s needs.
OAuth 2.0 Scopes
Scopes are used to grant an application different levels of access to data on behalf of the Customer. All requests for a token must therefore include one or more Scopes, to indicate which level of access is intended. The Valdit VAT Validation API uses two different scopes:
- The ‘vatnumberchecks:write’ scope is required for creating and updating VAT number Checks (POST and PUT Operations). The scope will also allow for retrieving VAT number Checks (GET Operation)
- The ‘vatnumberchecks:read’ scope is required for retrieving VAT number Checks (GET Operation)
- The ‘addresses:geocode’ scope is required for retrieving the structured Business Address (POST and PUT Operations).
Authenticating a client: Client Credentials Flow
Authenticating a Client (system) uses the standardized OAuth 2.0 Client Credentials Flow1 . A client_id and client_secret will be provided to you in order to be able to request tokens. It is important that these credentials are protected. If those credentials get compromised others may read or update your data.
The client_id and client_secret must be sent using HTTP basic authentication. The Authorization Header must follow the standards for Basic Authentication and thus contains ‘Basic’ followed by a Base64 encoded version of [client_id]:[ client_secret]. An example Basic Authorization header will be:
Authorization: Basic bXljbGllbnRpZDpteXZlcnkkZWNyZXRwdw==
Request the token
Requesting the token is done by sending a POST rquest to the token endpoint defined in paragraph 6.1. Insert the Basic Authorization header. Set the Content-Type to application/x-www-form-urlencoded and set the body of your POST to:
'grant_type=client_credentials&scope=vatnumberchecks:read vatnumberchecks:write addresses:geocode'
The scope should match the required scope as described above. Multiple scopes can be requested and must be separated by a space. Remember to url-encode the body to match the Content-type. The resulting raw version of the HTTP request is:
POST https://developer.valdit.com/identity/connect/token HTTP/1.1
Host: developer.valdit.com
Authorization: Basic bXljbGllbnRpZDpteXZlcnkkZWNyZXRwdw==
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&scope=vatnumberchecks%3Aread+vatnumberchecks%3Awrite+addresses%3Ageocode
Upon successful Authentication a JSON object is returned containing the Access Token:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz.......................",
"expires_in": 3600,
"token_type": "Bearer"
}
The received Access Token must be included as a Bearer token in the Authorization Header of any of the API calls:
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz…………………..
Please note that the Access Token should not be requested before every call. The Valdit Identity system issues tokens which are valid for between one and 24 hours, depending on the OAuth 2.0 flow that is used to request the token. The Lifetime of the token is indicated in the “expires_in” field in the response to the token request. You should only request a new token when your current token is about to expire.