Calling an API – HOW-TO



Most of the APIs will require form of authentication and authorization. If the used API requires no authorization, you can skip the next chapter and continue with the chapter “Calling an API”


Token Service

Token service is used to retrieve an access token used to authorize a web service client. The token service is part of the OAuth 2.0 protocol. For most of the APIs the “client_credentials” OAuth profile is used authenticating the application client.



Registering an application


To use any API there must be a client application registered.




Fill in a name, description and allowed quota.




Create a subscription – permission of the application to use the API








Generating an access token




It is possible to create a token from the API Store console or using a token web service



Generating an access token using the API Store console



Creating the token from the API Store console is recommended for development purposes or for creating a permanent “client credentials” (application) token.






When specifying a Validity Period it is possible to generate a permanent application token by using value -1. When creating a new access token from this console will revoke the existing access token.




Generating an access token using the Token web service


The API Manager needs to authenticate and authorize only the client application (not the end users), therefore the client credentials OAuth 2.0 profile is used.


curl -X POST \

     -d "grant_type=client_credentials&client_id=consumer-key&client_secret=consumer-secret" \



> POST /api/token HTTP/1.1

> User-Agent: curl/7.29.0

> Host:

> Accept: */*

> Content-Length: 111

> Content-Type: application/x-www-form-urlencoded





Where the consumer-key and consumer-secret values are taken from the application settings




Token service response sample:




  "scope":"am_application_scope default",





The client application should cache the application access token and it must track validity of the token. Once the access token is expired or revoked, new access token should be requested.



Access token scope


Some APIs may require special permissions (based on roles) - scope. To request a token with specific token is possible through the API DEV console or Token API service:



curl -X POST \

     -d "grant_type=client_credentials&client_id=consumer-key&client_secret=consumer-secret&scope=scope_name" \



Revoking an access token


An access token can be revoked using the revocation service



curl -X POST -d  "token=existing_token&grant_type=client_credentials&client_id=consumer-key&client_secret=consumer-secret" \



curl -X POST -d  "token=existing_token" \

     -H "Authorization: Basic Base64(consumer-key:consumer-secret)" \






Calling an API



Testing API services


It is possible to test the API and its usage using the API Store console


The authorized application and its key set (production or sandbox) needs to be selected once an access token is generated.







Using API Services


Example call:



curl -X GET \

    -H 'Accept: application/xml' \

    -H 'Authorization: Bearer 4717fa00-cc20-3414-b3b1-bc869b5eb4aa' \





Important headers: