Appendix A: Using Token-Based Authentication

Similar to the OpenID Configuration APIs and the Webhooks v3 APIs, the Custom Provider APIs use token-based authentication: you must obtain a configuration access token from your token endpoint before you can call any of the /custom-providers endpoints. That token endpoint will have a URL similar to the following, where e0a70b4f-1eef-4856-bcdb-f050fee66aae represents your Akamai customer ID:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/token

Note. Your token endpoint is assigned to you when Hosted Login is first provisioned. In addition to the token endpoint, you’ll also be given a configuration client and a token policy, both of which are needed obtain a configuration access token. 

For a more detailed look at configuration access tokens and how they’re acquired, we recommend that you look at the article API Security for Configuration. For now, we’ll simply note that you’ll need to use the POST method and make an API call to the token endpoint in order to get the required token. In addition to that, you must:

  • Configure Basic authentication for that API call. To do that, use the client ID of your configuration client as the username and the client secret of the configuration client as the password.

  • Add a pair of x-www-form-urlencoded body parameters to the API call. The first parameter (grant_type) must be set to client_credentials; this tells the token endpoint that you’re requesting a “generic” access token to be used for administrative purposes as opposed to an access token issued to a specific individual. The second parameter (scope) specifies the permissions that should be assigned to the token. Set the scope to *:**. This gives the bearer of the token permission to do anything that the token-based APIs can do, including call the Configurable IdP endpoints.

    If you’re using Postman to make your API calls your body parameter should look like this:


Note. At this point in time, *:** is the only scope that can be used with the Configurable IdP APIs. There is no way to limit a scope to just the Custom Provider API endpoints; instead, access is all-or-nothing.

If your API call succeeds, you’ll get back a response similar to this:

{
    "access_token": "z7S4iEe7KBRG8vMBPWRtJD66VH9SGMAIA56ol-loCln5MZOtGjmcy601tSh5IE6t",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "*:**"
}

A few things to note about the token you’ll be issued. First, the token value (shown in red) is the value used when you make an API call using the /custom-providers endpoints. For example, in Postman you’ll set the Authorization Type to Bearer token and then enter the access_token value into the Token field:

In addition to that: 

  • You get only an access token (no refresh token.
  • That access token expires after one hour (3600 seconds).

In other words, if you get an access token at 8:00 AM you can use that token until 9:00 AM, one hour after the token was issued. At that point the token expires, and – because you don’t have a refresh token – you’ll have to go back to the token endpoint and request a new access token. 

By the way, if you make an API call and get the following error, that usually means that your access token has expired:

{
    "error": "Forbidden"
}

If you see this error, requesting (and then using) a new access token will almost-always fix the problem.