OAuth Setup

OAuth Setup

API v1 uses the OAuth 2.0 Authorization Code flow for authentication. This page documents the confidential-client variant: your server holds a client_secret and presents it at the token endpoint, so PKCE is not required (the secret serves the same binding purpose). PKCE is supported if you want defense-in-depth — include code_challenge/code_challenge_method in the authorization URL and code_verifier in the token exchange.

This page walks through the full flow: registering a client, directing the user to Credal to authorize, exchanging the resulting code for an access token, and calling the API.

1. Register an OAuth client

Creating an OAuth client requires approval from your organization’s admin. To request one, ask your admin to contact support@credal.ai.

After registration you’ll receive a client ID and client secret. Keep the client secret secure — treat it like a password.

2. Direct the user to Credal to authorize

Send the user to the Credal authorization endpoint. They’ll be asked to sign in (if not already) and approve the requested scopes.

https://app.credal.ai/api/oauth/authorize
  ?response_type=code
  &client_id=<your_client_id>
  &redirect_uri=<your_redirect_uri>
  &scope=api:agent:message:*
  &state=<random_value>

After the user approves, Credal redirects to your redirect_uri with a short-lived authorization code:

https://your-app.com/callback?code=<authorization_code>&state=<random_value>

3. Exchange the code for an access token

The authorization code is not an access token. You must exchange it by making a server-side POST request to the token endpoint. Do not skip this step.

$
curl -X POST https://app.credal.ai/api/oauth/token \
>
  -H "Content-Type: application/x-www-form-urlencoded" \
>
  -d "grant_type=authorization_code" \
>
  -d "code=<authorization_code>" \
>
  -d "client_id=<your_client_id>" \
>
  -d "client_secret=<your_client_secret>" \
>
  -d "redirect_uri=<your_redirect_uri>"

The response contains the tokens you’ll use to call the API:

1
{
2
  "access_token": "eyJ...",
3
  "token_type": "Bearer",
4
  "expires_in": 3600,
5
  "refresh_token": "eyJ..."
6
}

A few things to note:

• The authorization code expires in 10 minutes and is single-use. Exchange it immediately after receiving it.
• The redirect_uri must match the one used in step 2 exactly.

4. Call the API

Pass the access_token to the Credal SDK:

1
import credal
2
3
client = credal.CredalClient(token=access_token)
4
5
response = client.agents.send_message(
6
    agent_id="your-agent-id",
7
    conversation=credal.NewConversation(),
8
    message="Hello!",
9
)

5. Refresh the access token

Access tokens expire after 1 hour. Use the refresh_token to get a new one without sending the user through the browser flow again:

$
curl -X POST https://app.credal.ai/api/oauth/token \
>
  -H "Content-Type: application/x-www-form-urlencoded" \
>
  -d "grant_type=refresh_token" \
>
  -d "refresh_token=<your_refresh_token>" \
>
  -d "client_id=<your_client_id>" \
>
  -d "client_secret=<your_client_secret>"

Refresh tokens are valid for 30 days and are rotated on every use — each refresh response includes a new refresh_token that replaces the old one. Always persist the new value; the previous token is immediately invalidated. If a refresh token expires, the user will need to go through the browser authorization flow again.