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 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 one of your Web services profiles. 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>"
}

For example, here is the result of a successful authentication using Postman:

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

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

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

If you use Swagger UI to test your operations, enter Bearer <access token value> in the authorization window:

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/. See Basic authentication realm.

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>
Header parameters:
Authorization: Basic <Base64 credentials>
Content-Type: application/x-www-form-urlencoded

Replace <Token Endpoint URL> with your token endpoint URL (available on the Web Services Profile page in Caspio).

The value for the Authorization header parameter <Base64 credentials> is Client_ID:Client_Secret, encoded using a third-party tool such as https://www.base64encode.org/. See Basic authentication realm below.

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.

Basic Authentication Realm

In the Alternative Authentication and Token Renewal sections above, you need to create a header parameter for Basic Authentication Realm <Base64 credentials>.

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.