Token Service Overview

Users need access tokens to invoke APIs subscribed under an application. Access tokens are passed in the HTTP header when invoking APIs. The Atlas API manager provides a Token API that you can use to generate and renew user and application access tokens. The response of the Token API is a JSON message. You extract the token from the JSON and pass it with an HTTP Authorization header to access the API.

Obtaining a Token

You can obtain an access token by providing the resource owner's username and password as an authorization grant. It requires the base64 encoded string of the consumer-key:consumer-secret combination. You need to meet the following prerequisites before using the Token API to generate a token.

Please refer to the WSO2 IS documentation for a detailed explanation on this grant type with the use of a sequence diagram.

Prerequisites

Before you can use an authenticated service endpoint, you must have the following information:

  1. A valid user account and password for accessing the Atlas API. Your account information will be provided to you by your implementation team.
  2. An application defined within the Atlas API management console.
  3. A valid consumer key and consumer secret pair. You create these for each application you create within the Atlas API management framework.

Invoking the Token API to generate tokens

Step 1: Combine the consumer key and consumer secret keys in the format consumer-key:consumer-secret and encode the combined string using base64. Encoding to base64 can be done using the URL: http://base64encode.org.

Here's an example consumer key and secret combination: wU62DjlyDBnq87GlBwplfqvmAbAa:ksdSdoefDDP7wpaElfqvmjDue. And here's the string encoded from the example: d1U2MkRqbHlEQm5xODdHbEJ3cGxmcXZtQWJBYTprc2RTZG9lZkREUDd3cGFFbGZxdm1qRHVl.The encoded string should be used in the header of the cURL command.

Step 2: Access the Token API by using a REST client such as cURL, with the following parameters. Assuming that both the client and the API Gateway are run on the same server, the token API url is https://localhost:8243/token

payload - "grant_type=password&username=<username>&password=<password>&scope=<scope>". Replace the <username> and <password> values as appropriate.

Tip: <scope> is optional.

If you define a scope for an API's resource, the API can only be accessed through a token that is issued for the scope of the said resource. For example, if you define a scope named 'update' and issue one token for the scopes 'read' and 'update', the token is allowed to access the resource. However, if you issue the token for the scope named 'read', the request to the API will be blocked.
headers - Authorization: Basic <base64 encoded string>, Content-Type: application/x-www-form-urlencoded. Replace the <base64 encoded string> as appropriate.

For example, use the following cURL command to access the Token API. It generates two tokens as an access token and a refresh token. You can use the refresh token at the time a token is renewed .

curl -k -d "grant_type=password&username=&password=" \ -H "Authorization: Basic d1U2MkRqbHlEQm5xODdHbEJ3cGxmcXZtQWJBYTprc2RTZG9lZkREUDd3cGFFbGZxdm1qRHVl" \ -H "Content-Type: application/x-www-form-urlencoded" \ https://localhost:8243/token

You receive a response similar to the following:

JSON Response: { "scope":"default", "token_type":"Bearer", "expires_in":3600, "refresh_token":"ca5a51f18b2edf4eaa9e4b871e42b58a", "access_token":"f2c66f146278aaaf6513b585b5b68d1d" }