API

Get started

The Custom Provider API uses token-based authentication, That means you need to obtain an administrative access token before you can call any of the /custom-providers operations. Note that your 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


📘

Your token endpoint is assigned when Identity Cloud 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 Get started topic for the Hosted Login API. 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 operation. 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 response body members to the API call. The first parameter (grant_type) needs to be set to client_credentials. This grant type tells the token endpoint that you’re requesting a “generic” access token to be used for administrative purposes rather than an access token issued to a specific individual. The second parameter (scope) specifies the permissions to be assigned to the token. For custom providers, set the scope to *:**. This gives the bearer of the token permission to do anything that the Custom Provider API can do.

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



📘

At this point in time, *:** is the only scope available for the Custom Provider APs.


If your operationl 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 itself. First, the token value is the value used with Xustom Provider operations. For example, in Postman you’ll set the Authorization Type to Bearer token and then enter the access_token value in the Token field:

In addition, keep in mind that: 

  • You get only an access token. You don't get a refresh token as well.

  • The 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 need to go back to the token endpoint and request a new access token. 

Incidentally, 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.