Oauth setup
OAuth Setup
Section titled “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
Section titled “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
Section titled “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>| Parameter | Description |
|---|---|
response_type |
Always code |
client_id |
Your client ID from step 1 |
redirect_uri |
The URL Credal redirects back to after authorization (must match your registered redirect URI exactly) |
scope |
Space-separated list of scopes. api:agent:message:* lets you send messages to agents. |
state |
A random, unguessable value you generate (e.g. a UUID). Credal echoes it back in the redirect — your callback must verify it matches before exchanging the code, to prevent CSRF attacks. |
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
Section titled “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>"import requests
response = requests.post(
"https://app.credal.ai/api/oauth/token",
data={
"grant_type": "authorization_code",
"code": authorization_code,
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
"redirect_uri": REDIRECT_URI,
},
)
tokens = response.json()
access_token = tokens["access_token"]
refresh_token = tokens["refresh_token"]const response = await fetch("https://app.credal.ai/api/oauth/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "authorization_code",
code: authorizationCode,
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
redirect_uri: REDIRECT_URI,
}),
});
const { access_token, refresh_token } = await response.json();The response contains the tokens you'll use to call the API:
{
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "eyJ..."
}A few things to note:
- The authorization code expires in 10 minutes and is single-use. Exchange it immediately after receiving it.
- The
redirect_urimust match the one used in step 2 exactly.
4. Call the API
Section titled “4. Call the API”Pass the access_token to the Credal SDK:
import credal
client = credal.CredalClient(token=access_token)
response = client.agents.send_message(
agent_id="your-agent-id",
conversation=credal.NewConversation(),
message="Hello!",
)import { CredalClient } from "@credal/sdk";
const credal = new CredalClient({
token: accessToken,
environment: "https://app.credal.ai/api/v1",
});
const response = await credal.agents.sendMessage({
agentId: "your-agent-id",
conversation: { type: "new" },
message: "Hello!",
});5. Refresh the access token
Section titled “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>"response = requests.post(
"https://app.credal.ai/api/oauth/token",
data={
"grant_type": "refresh_token",
"refresh_token": refresh_token,
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
},
)
tokens = response.json()
access_token = tokens["access_token"]
refresh_token = tokens.get("refresh_token", refresh_token) # Credal rotates refresh tokens; persist the new valueRefresh 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.