Authenticating REST API

3 minutes to read

The Caspio REST API uses OAuth 2.0 client credentials flow. This is a two-step process: first you obtain an access token, then you include that token in all subsequent API requests.

Authentication

Obtaining an access token request

Method: POST
URL: <Token Endpoint URL>
Body: grant_type=client_credentials&client_id=<Client ID>&client_secret=<Client Secret>

Replace <Token Endpoint URL>, <Client ID>, and <Client Secret> with credentials from your API profile. If you do not have a profile yet, create one.

If the authentication request is successful, you will receive the access token and refresh token:

{
  "access_token": "<access token value>",
  "token_type": "bearer",
  "expires_in": 86399,
  "refresh_token": "<refresh token value>"
}

From this point on, you will use your resource endpoint instead of the token endpoint. Every request must include the following header parameters:

Parameter name: Authorization
Parameter value: Bearer <access token value>

Replace <access token value> with your actual access token.

Token expiration and renewal

Access tokens expire after 24 hours. Refresh tokens expire after 1 year or, if they have never been used, after 60 days. Refresh tokens are limited to 1,000 per Caspio account. If you generate a new refresh token after reaching this limit, the oldest token is automatically invalidated.
After the access token expires, a 401 Unauthorized status code is returned. At this point, you can re-authenticate using the instructions above or refresh your token as described below.

Making a refresh token request:

Method: POST
URL: <Token Endpoint URL>
Body:grant_type=refresh_token&refresh_token=<refresh token value>&client_id=<Client ID>&client_secret=<Client Secret>

Replace <Token Endpoint URL>, <Client ID>, and <Client Secret> with credentials in your API profile.

After the refresh token expires, a 401 Unauthorized status code is returned, and the client must re-authenticate using the Client ID and Client Secret.

Alternative authentication

As an alternative to including credentials in the request body, a client can use the HTTP Basic authentication scheme. In this case, the authentication request is set up as follows:

Method: POST
URL: <Token Endpoint URL>
Body: grant_type=client_credentials
Header parameter:
Authorization: Basic <Base64 credentials >

The header parameter <Base64 credentials > is the string Client_ID:Client_Secret encoded using a third-party tool such as https://www.base64encode.org/.
It is constructed as follows:

Client_ID:Client_Secret → Base64 encode → <Base64 credentials>

The value <Base64 credentials> is created by encoding the string Client_ID:Client_Secret using the RFC2045-MIME variant of Base64. Your programming language may provide a built-in method to perform this encoding.

Making a refresh token request:

Method: POST
URL: <Token Endpoint URL>
Body: grant_type=refresh_token&refresh_token=<refresh token value>
Header parameter:
Authorization: Basic <Base64 credentials>
Content-Type: application/x-www-form-urlencoded

Replace  with your <Token Endpoint URL> (available in your API Profile) and <Base64 credentials>  generated as described above.