Authenticating REST API

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

You must replace Request 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":"",
"token_type":"bearer",
"expires_in":86399,
"refresh_token":""}

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:    
Body:   grant_type=client_credentials
Header parameter: 
Authorization: Basic

The header parameter 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 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:    
Body:   grant_type=refresh_token&refresh_token=
Header parameters:
Authorization: Basic 
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 is “Basic 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. 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.