Overview

This article explains how to use OAuth2 to interact with Clayton APIs. OAuth2 is a standard that allows third-party applications to securely access your Clayton data. This can be useful for writing tools like CLI scripts or web applications that interact with your Clayton workspace.

Authorization Code Grant

Clayton currently uses the OAuth2 Authorization Code Grant flow ( learn more ), which is designed for web applications. While ideal for web apps, this flow can also be used for some machine-to-machine (M2M) integrations.

How to use OAuth Authorization Code Grant flow for machine-to-machine integrations

The Client Credentials Grant is generally preferred for M2M integrations because it doesn't involve user interaction. However, Clayton currently only supports the Authorization Code Grant. We'll explain how to use it in the following steps.

Register an OAuth Application

Choose a Name: choose a descriptive name for your application (e.g., "My CLI Script"). This name helps identify the application when Clayton generates your credentials.
Configure Redirect URIs: you need to provide redirect URIs. These are URLs where users are redirected after the consent step (explained later).

For M2M Integration: Check the "This is a native or CLI app" flag. This tells Clayton to redirect the consent step back to Clayton itself, where the user can grab the authorization code.

Important: Once registered, you'll receive client credentials (client ID and client secret). These credentials are crucial and cannot be retrieved later. Store them securely.

Give the consent and get the Authorization Code

The Authorization Code grant is used when an application exchanges an authorization code for an access token ( next steps ). After the registration, edit your application to copy the consent URL.

This step depends on the "This is a native or CLI app" setting. Since you chose this option, paste that URL in your browser will display a web page where you can grant consent and obtain the authorization code.

Important: The consent step redirects to a Clayton page that displays the authorization code. Make sure to copy and store the Authorization Code securely.

Exchange the Authorization Code for an Access Token

The Authorization Code allows your application to obtain an Access Token. Here's an example using curl (replace placeholders with your actual values):

curl --request POST \
 --url "https://app.clayton.io/oauth2/token?code=$AUTH_CODE" \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data "client_id=$CLIENT_ID" \
 --data "client_secret=$CLIENT_SECRET" \
 --data 'grant_type=authorization_code' \
 --data 'scope=workspace' \
 --data 'redirect_uri=https://app.clayton.io/authorized'

This command retrieves your first access token.

{"access_token":"xyz789...","refresh_token":"abc123...","scope":"workspace","token_type":"Bearer","expires_in":5399}

Perform API calls

Every time you need, use the Refresh Token to get a new valid Access Token:

curl --request POST \
 --url "https://app.clayton.io/oauth2/token" \
 --header "content-type: application/x-www-form-urlencoded" \
 --data grant_type=refresh_token \
 --data "client_id=$CLIENT_ID" \
 --data "client_secret=$CLIENT_SECRET" \
 --data "refresh_token=$REFRESH_TOKEN"

Then use the latest valid Access Token to authenticate an API call such as:

curl --request GET \
 --url "https://app.clayton.io/api/workspaces" \
 --header "accept: application/json" \
 --header "content-type: application/json" \
 --header "authorization: Bearer $ACCESS_TOKEN"