Getting an Authentication Token

The Identity Cloud is beginning to transition to token-based authentication for API endpoints, and Webhooks v3 is one of the first major features to rely on this authentication method. That means that, in order to call a webhooks endpoint, you need to:

  1. Use a configuration client to connect to the token exchange endpoint and obtain a token. You must present the client ID and client secret of the configuration client in order to get a token.
     
  2. Use Bearer Token authentication and the value returned from the token exchange endpoint to make a webhooks API call. For example, in Postman your authentication will look similar to this:

Before we go any further, we should explain what a configuration client is. In the OAuth world, a client works on your behalf in order to obtain authorization of some sort; in the case of webhooks, the client works on your behalf to obtain a bearer token. The Identity Cloud’s version of OAuth supports three types of clients:

  • Confidential clients, which can be entrusted with a client secret. 
  • Public clients, which can’t be trusted with a client secret. 
  • Configuration clients, which enable you to obtain access tokens that authorize you to use protected resources such as Identity Cloud APIs. 

The Identity Cloud token endpoint can only be access by using a configuration client.

Note. Although it’s easy to do, don’t confuse OAuth configuration clients with API clients: configuration clients are only used for obtaining tokens. In fact, if you look at the Manage Properties page in Console, you won’t see any configuration clients listed there. That’s because the Manage Properties page is for managing API clients, not configuration clients. 

When you subscribe to Webhooks v3, your Akamai representative will set up a configuration client for you, and provide you with the client ID and client secret. (At the moment, there’s no way for you to create the initial configuration client on your own.) 

In addition, you’ll also be given a token policy. Token policies serve two purposes. First, they specify how long tokens remain valid: by default, access tokens remain valid for 60 minutes (3600 seconds) and refresh tokens remain valid for 90 days (7776000 seconds). In addition to that, token policies specify the scopes that the configuration client associated with the policy has access to (something we’ll discuss in a moment). Your initial token policy, which will also be provided by your Identity Cloud representative, will look similar to this:

{
   "id": "2dcae965-0d56-4961-a98e-f98583e30bb9",
   "accessTokenLifetime": 3600,
   "allowedScopes": [*:webhooks/ **],
   "refreshTokenLifetime": 7776000,
   "title": "Webhooks Token Policy",
   "_links": {
       "self": {
           "href": "/config/01000000-0000-3000-9000-000000000000/tokenPolicies/2dcae965-0d56-4961-a98e-f98583e30bb9"
       }
   }
}


After you’ve been given a configuration client and a token policy, you can then use the client ID and client secret in order to obtain a webhooks access token. Note that the configuration client provided to you can only be used to obtain a webhooks access token; the scope claim called out in the token policy provides full access to the /webhooks API endpoints and nothing else:

"scope": "*:webhooks/**"

So how do you actually get an access token? To do that you need to call the /{customer_id}/login/token endpoint; prior to making that call, you must configure Basic authentication (using the client ID as the username and the client secret as the password), and specify two additional request keys. For example, in Postman your authorization should look similar to this:

If you’re using Curl, your authorization header will look like this:

-H 'Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg='

You'll also need to configure the request’s grant_type and scope, which must be configured as x-www-url-encoded body parameters. For example:

The grant_type must be set to client_credentials; this tells the token endpoint that you're using the client credentials grant to request an access token. The client credentials grant is employed when requesting access to system resources such as API endpoints. This grant type also tells the token endpoint that you are using the credentials of a configuration client to request the token, and are not exchanging an authorization code or a refresh token for an access token.

Meanwhile, the scope key must be set to the same scope specified in your token policy. In this example, that means that the scope is set to *:webhooks/**.

A complete Curl command for requesting an access token will look similar to this:

curl -X POST \
  https://v1.api.us.janrain.com/01000000-0000-3000-9000-000000000000/login/token \
  -H 'Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=' \
  -F grant_type=client_credentials \
  -F 'scope=*:webhooks/**'

At that point you can make your API call. Assuming you supplied the correct information, you should get back a response that includes an access token:

{
   "access_token": "Xk7EzdpGq5GPQcsxCWM2SxdlwU_iTsA4i2Px4TEzBrfLIvddjnDVBJxjPDuCARHH",
   "expires_in": 3600,
   "token_type": "Bearer",
   "scope": "*:webhooks/**"
}

The access token value -- Xk7EzdpGq5GPQcsxCWM2SxdlwU_iTsA4i2Px4TEzBrfLIvddjnDVBJxjPDuCARHH – is the value you’ll use when making your webhooks API call.

Two quick notes about the access token you get back. First, the access token can be used for one hour (3600 seconds); after that the token expires, and any subsequent API calls that use the expired token will fail. If you see an error like this, that typically means that your token has expired:

But that’s fine: all you have to do is get a new token and you can resume making API calls until that token expires.

Second, you might have noticed that no refresh token is returned along with the access token. That’s by design: refresh tokens typically aren’t returned with a client_credentials grant. Because these tokens are used for administrative purposes, it’s a good practice to keep token lifetimes relatively short, and to forego the use of refresh tokens. Should one of these tokens somehow fall into the wrong hands, there would only be a limited amount of time (60 minutes at most) during which that token could be misused.