API v2 Authentication

Authentication & OAuth (API v2)

How to obtain and use an OAuth 2.0 access token to authenticate Clew API v2 requests

Contents

• 1. Introduction & Context
• 2. Key Features & Functions
• 3. Requirements
• 4. Step-by-Step Guide
  • Obtain an access token
  • Use an access token
• 5. Common Issues & Troubleshooting
• 6. Related Articles

1. Introduction & Context

This article explains how to authenticate requests to the Clew API v2 using OAuth 2.0. Clew API v2 requests are authenticated with an OAuth 2.0 Bearer Token (an access token), which you obtain through the Client Credentials Flow and then include in the authorization header of each request.

Who is it for? Developers and integrators building server-to-server integrations against the Clew API v2.

What does it impact? The access token grants API access under the scope of the authorised Application. Tokens expire after a set period, so integrations should be built to request a new token or use the refresh token when the current one expires.

2. Key Features & Functions

• Bearer token authentication: API v2 requests are authenticated with an OAuth 2.0 access token passed in the authorization header.
• Client Credentials Flow: an authorised Application in Clew exchanges its client ID and client secret for an access token, suited to server-to-server integrations.
• Token expiry and refresh: the response returns the token, its type, an expiry period (expires_in), a refresh token, and the granted scope.

3. Requirements

• An authorised Application created in Admin, which provides the client_id and client_secret.
• Access to the Clew API v2 for your instance.
• The base URL of your Clew instance, used in place of the <your-clew-instance-url> placeholder in the examples.

4. Step-by-Step Guide

Obtain an access token

Use the Client Credentials Flow to obtain an access token. This flow uses an authorised Application in Clew.

1. Create an Application in Admin to obtain your client_id and client_secret.
2. Perform the following request to obtain an access_token:

POST https://<your-clew-instance-url>/oauth/token
BODY
grant_type: client_credentials
client_id: <client_id>
client_secret: <client_secret>
scope: public

Example cURL request:

curl --request POST \
  --url https://<your-clew-instance-url>/oauth/token \
  --data grant_type=client_credentials \
  --data client_id=<client_id> \
  --data client_secret=<client_secret> \
  --data scope=public

The following response is an example of the end result of the flow:

{
  "access_token": "6iqofj5zHR5bfZFlpqJxuLP5bA1uWKnOAt9kaaAwTf8",
  "token_type": "Bearer",
  "expires_in": 10800,
  "refresh_token": "1uX26iFkuilkx6KoACjt3yrtcDshTSt2MxJy8EVS3AM",
  "scope": "public",
  "created_at": 1604986678
}

Use an access token

Include the access token in the authorization header of your API requests. You can perform the following request to verify the access token is working:

GET https://<your-clew-instance-url>/api/v2/users/current.json
HEADER
authorization: bearer <access_token>

Example cURL request:

curl --request GET \
  --url https://<your-clew-instance-url>/api/v2/users/current.json \
  --header 'authorization: bearer <access_token>'

5. Common Issues & Troubleshooting

Best practices:

• Store your client_secret and access tokens securely, and never expose them in client-side code.
• Build your integration to handle token expiry using the expires_in value and the refresh token.
• Verify a new token with the users/current.json endpoint before using it in production requests.

6. Related Articles

• Logging in to the Clew Mobile App
• Adding New Users