Overview
This article explains how to use OAuth2 to interact with Code Reviews APIs. OAuth2 is a standard that allows third-party applications to securely access your Code Reviews data. This can be useful for writing tools like CLI scripts or web applications that interact with your Code Reviews workspace.
Authorization Code Grant
Code Reviews 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, Code Reviews 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 Code Reviews 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 Code Reviews to redirect the consent step back to Code Reviews 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 Code Reviewspage 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"