Page last modified 07:26, 6 May 2016 by kari_admin


    Version as of 16:24, 7 Dec 2021

    to this version.

    Return to Version archive.

    View current version


    XMLdation API supports authentication with OAuth 2.0 Bearer Token Authentication method. Authorization header must be set to all requests made to the XMLdation API, excluding the get token authentication request. API functionality is enabled per user and is managed by XMLdation. If you need API usage privileges, please contact XMLdation at

    OAuth Token Endpoint URLs

    OAuth 2.0 Bearer Token Authentication

    XMLdation API uses OAuth 2.0 Bearer Token Authentication to authenticate the valid user account. Following header must be passed to all requests (excluding the token retrieval):

    Authorization: Bearer <API token>

    More information about OAuth 2.0 Bearer Token Authentication available at rfc2617.

    Generating OAuth Token

    OAuth Token is a key to autenticate user to API Service. Same username and password combo is used to access XMLdation Service and API Service OAuth Token retrieval. OAuth Token is always defined per user account. User can have one OAuth Token active per time. OAuth Token expires in 30 minutes and must be regenerated either VIA Refresh Token or by generating a new one with ClientId:ClientSecret and Username/Password combo.

    In case existing OAuth Token expires or is lost, new OAuth Token must be generated via API Service.

    New OAuth Token along with a Refresh Token can be generated with following curl command


    curl --user ClientId:ClientSecret  -k -d "grant_type=password&username=xmldation/Username&password=Password" -H "Content-Type:application/x-www-form-urlencoded"


    • ClientId is provided by XMLdation
    • ClientSecret is provided by XMLdation
    • Username is XMLdation Service username
    • Password is XMLdation Service password

    OAuth Token can be refreshed VIA Refresh Token with following curl command

    (This method should be used when the OAuth Token has expired. It doesn't require the username&password combination)

    curl --user ClientId:ClientSecret  -k -d "grant_type=refresh_token&refresh_token=RefreshToken" -H "Content-Type:application/x-www-form-urlencoded"



    • ClientId is provided by XMLdation
    • ClientSecret is provided by XMLdation
    • RefreshToken is provided by API Service upon New OAuth Token generation

    Error messages

    In case of authentication failure the API will response with HTTP 401 response code. Also error message body is returned.

    Unauthorized error message is returned in following cases:

    • Authorization header is missing
    • Authorization header content is invalid
    • username + apikey is invalid
    • User does not have permissions to given product code (e.g. in /v1/validate/{pcode})


    If you you have checked that your authentication details are correct, but you still get error messages, please contact XMLdation for further assistance.

    401 unauthorized response body

    Response is returned in application/json format.

    HTTP/1.1 401 Unauthorized

      "error" : {
        "status" : 401,
        "message" : "Unauthorized"