Authenticating REST API

4 minutes to read

Caspio REST API authentication is based on OAuth 2.0 protocol and supports client_credentials flow, meaning that before a client can access Caspio resources, it must be authenticated using Client ID/Secret pair that can be found on Caspio REST API profile page or profile properties. And all REST calls should be made in HTTPS. When successfully authenticated, a token is generated that must be used in all follow on calls to the resources endpoint.

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 those provided in your Caspio account as shown below.

The image below shows a successful authentication call using Firefox RESTClient (add-on).

If authentication request is successful, client will receive access/refresh token pair that looks like:

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

From this point on you will be using your resource endpoint instead of the token endpoint and every request will have to include the following header parameter:

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

You must replace <access token value> with the one provided in the previous step.

If you use Swagger UI to test your operations, enter the bearer <access token value> above in the authorization dialog window as shown below.

If you continue using RESTClient to test your operations, enter the bearer above in the Request Header dialog window as shown below.

Alternative Authentication

As an alternative to including credentials in the request body, a client can use the HTTP Basic authentication scheme. In this case, authentication request will be setup in the following way:

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 with the third-party website 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, 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 will be automatically invalidated.

After the access tokens expire, 401 Unauthorized status code is returned. At this point you can re-authenticate using the instructions above, or you could refresh your token as described below. The choice is yours and depends on your use case and preference.

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 Request URL with your token endpoint URL (the one in Caspio on the Web Services Profile page).

The value for Authorization header parameter <Base64 credentials> is “Client_ID:Client_Secret”, where Client_ID:Client_Secret should be encoded with the third-party website: https://www.base64encode.org/. See Basic Authentication Realm below.

After the expiration of the refresh token, 401 Unauthorized status code will be returned and the client should re-authenticate using Client ID/Secret pair.

Basic Authentication Realm

In Alternative Authentication and Token Renewal sections above you will need to create a header parameter for Basic Authentication Realm <Base64 credentials>. It is constructed by creating the string “Client_ID:Client_Secret”, and encoding it using the RFC2045-MIME variant of Base64. Your programming language may have a simple way of achieving this.