Authentication – To The Point

If you're already experienced in working with OAuth 2.0 APIs, these are all the details you need.

We only implement the Authorization Code flow of the OAuth specification.

Registering an Application

If you're a library owner, or if you have a sandbox account: get your client credentials from the library settings page. Go to the API Settings tab, click Register Application and copy the Client ID and the Client Secret.

As a partner, apart from your sandbox library, you also get a set of client credentials from us that allow you to connect to other libraries.

Generating Tokens

The authorization URL is https://api.apicbase.com/oauth/authorize/. A sample URL therefore looks like this:

https://api.apicbase.com/oauth/authorize/?response_type=code&client_id=MY_CLIENT_ID&scope=SCOPE1+SCOPE2>

If your application has no redirect URL configured, you'll be redirected to an Apicbase page from where you can copy the authorization code.

The authorization code expires after one minute. When trying to get a token with an expired authorization code, the authorization server will respond with an "invalid_grant" error.

Check which scopes your application needs based on the endpoints that you require access to.

The access token URL is https://api.apicbase.com/oauth/token/. Make your authorization requests with the following payload:

grant_type="authorization_code",
code="YOUR_AUTHORIZATION_CODE",
redirect_uri="YOUR_REDIRECT_URI",
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET"

Refreshing Tokens

Access tokens expire one week after they're generated. The refresh tokens don't expire automatically. You can still refresh an access token after it has expired with its associated refresh token.

We also provide a token introspection endpoint where you can check details for the token that you currently hold, including for how long it's still valid, if you wish to include this in your application's authentication flow. Make a POST request to https://api.apicbase.com/oauth/introspect/ like so:

curl -X POST -d "token=MY_ACCESS_TOKEN&client_id=MY_CLIENT_ID&client_secret=MY_CLIENT_SECRET&refresh_token=MY_REFRESH_TOKEN" \
https://api.apicbase.com/oauth/introspect/

If the token is valid, belongs to the authenticated client and is not expired, the server will reply with info:

{
    "active": true,
    "scope": "library sales accounts procurement",
    "exp": 1613120953,
    "client_id": "MY_CLIENT_ID",
    "username": "[email protected]"
}

If the token is valid but expired, the server will reply with 200 OK but the following contents:

{
    "active": false
}