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
Body:   grant_type=client_credentials&client_id=Client ID&client_secret=Client Secret

You must replace Token Endpoint, 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",
"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.

Below is an example of how the authorization parameter is entered into Firefox RESTclient:

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:    Your token endpoint
Body:   grant_type=client_credentials
Header parameter:
Authorization: Basic <Basic authentication realm>

Token Expiration and Renewal

Access tokens expire in 24 hours and refresh tokens expire in 1 year.

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
Body:   grant_type=refresh_token&refresh_token=<refresh token value>
Header parameters:
Authorization: Basic <Basic authentication realm>
Content-Type: application/x-www-form-urlencoded

Replace Token Endpoint with your token endpoint as shown in the first image above.

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. It is constructed by creating the string “Client_ID:Client_Secret”, and encoding it using the RFC2045-MIME variant of Base64. You programming language may have a simple way of achieving this.