Authentication


Generate Access Tokens

You need access tokens to invoke APIs subscribed under an application. Access tokens are passed in the HTTP header when invoking the APIs. We provide 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.

The following topics explain how to generate access tokens and authorize them. Sphereon supports the three common authorization grant types.

1. Generating Access Tokens with User Credentials - Password Grant Type

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

Instead of using the Token API, you can generate access tokens from the API Store's UI in order to quickly start testing your code. 

Prerequisites

  • A valid user account in the API Store. You can do a self sign up if you don't have an account.
  • A valid consumer key and consumer secret pair. Initially, these keys must be generated through the API Store by clicking the Generate link on My Subscriptions page.

Invoking the Token API to generate tokens

  1.  Combine the consumer key and consumer secret keys in the format consumer-key:consumer-secret and encode the combined string using base64. For quick testing you can do the encoding to base64 online using http://base64encode.org
    Here's an example consumer key and secret combination: wU62DjlyDBnq87GlBwplfqvmAbAe:ksdSdoefDDP7wpaElfqvmjDua.
  2. Access the Token API by issuing a POST request using a REST client such as cURL, the SDK or your application to https://gw.api.cloud.sphereon.com/token , with the following parameters.
    • payload :  "grant_type=password&username=<username>&password=<password>&scope=<scope>". Replace the <username> and <password> values as appropriate with your store username and password. The scope is optional. If a scope has been defined for an API's resource, the API can only be accessed through a token that is issued for the scope of said resource. For example, if a scope named 'update' has been defined and you have issued 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 with the consumer key and secret combination

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 has to be renewed.

curl -k -d "grant_type=password&username=<username>&password=<password>" -H "Authorization: Basic SVpzSWk2SERiQjVlOFZLZFpBblVpX2ZaM2Y4YTpHbTBiSjZvV1Y4ZkM1T1FMTGxDNmpzbEFDVzhh" -H "Content-Type: application/x-www-form-urlencoded" https://gw.api.cloud.sphereon.com/token


You receive a response similar to the following:

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

2. TODO: SAML2 Bearer Tokens with OAuth2 - SAML Extension Grant Type
3. TODO: Access Tokens with Authorization Code - Authorization Code Grant Type

 

Renewing access tokens

After an access token is generated, sometimes you might have to renew the old token due to expiration or security concerns. You can renew an access token using a refresh token, by issuing a REST POST call to the Token API at https://gw.api.cloud.sphereon.com/token with the following parameters.

  • payload: "grant_type=refresh_token&refresh_token=<refreshtoken>&scope=PRODUCTION". Replace the <refreshtoken> value with the refresh token generated in the previous step.
  • headers: Authorization :Basic <base64 encoded string>, Content-Type: application/x-www-form-urlencoded. Replace <base64 encoded string> as appropriate.


For example, the following cURL command can be used to access the Token API.


curl -k -d "grant_type=refresh_token&refresh_token=<refreshtoken>&scope=PRODUCTION" -H "Authorization: Basic \
SVpzSWk2SERiQjVlOFZLZFpBblVpX2ZaM2Y4YTpHbTBiSjZvV1Y4ZkM1T1FMTGxDNmpzbEFDVzhh" -H "Content-Type: application/x-www-form-urlencoded" \
https://gw.api.cloud.sphereon.com/token

You will receive a response similar to the following:

{
"scope":"default",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"7ed6bae2b1d36c041787e8c8e2d6cbf8",
"access_token":"b7882d23f1f8257f4bc6cf4a20633ab1"
}


The above JSON response grants you a renewed access token along with a refresh token, which you can use the next time you renew the access token. The access toeken is valid for 1 hour (3600 seconds) after which the refresh token is needed. A refresh token can be used only once.

 

Revoking access tokens

After issuing an access token, you can revoke it in case of theft or a security violation. You can do this by calling the Revoke API using a utility like cURL. The Revoke API's endpoint URL is https://gw.api.cloud.sphereon.com/revoke.

Parameters required to invoke this API are as follows:

  • The token to be revoked
  • Consumer key and consumer secret key. Must be encoded using Base64 algorithm
    For example: curl -k -v -d "token=<ACCESS_TOKEN_TO_BE_REVOKED>" -H "Authorization: Basic aFNOM3k0aVFHVUNVZnZvdmFrVXE1U3ExQ1RRYTpYMmRvVFZSeFhEN1FfT2xLOWtzQlB2UkJCbFVh"Content-Type: application/x-www-form-urlencoded https://gw.api.cloud.sphereon.com/revoke

You will receive an empty response with the HTTP status as 200. The following HTTP headers are returned:

Revokedaccesstoken: a0d210c7a3de7d548e03f1986e9a5c39
Authorizeduser: user@example.com
Revokedrefreshtoken: 5e87a8235cd4d066e15c4c989f5ecf94
Content-Type: text/html
Pragma: no-cache
Cache-Control: no-store
Date: Tue, 31 Aug 2016 14:30:16 GMT
Transfer-Encoding: chunked

Note that if you use an invalid access token, you still receive an empty response with the HTTP status as 200 but only the following HTTP headers are returned:

Content-Type: text/html
Pragma: no-cache
Cache-Control: no-store
Date: Tue, 23 Aug 2016 19:31:45 GMT
Transfer-Encoding: chunked


Please note that even after revoking a token, it might still be available in the cache to consumers until the cache expires in approximately 15 minutes.