# 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>
```

| 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

**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.

:::code-group
```bash
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>"
```

```python
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"]
```

```typescript
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:

```json
{
  "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_uri` must match the one used in step 2 exactly.

### 4. Call the API

Pass the `access_token` to the Credal SDK:

:::code-group
```python
import credal

client = credal.CredalClient(token=access_token)

response = client.agents.send_message(
    agent_id="your-agent-id",
    conversation=credal.NewConversation(),
    message="Hello!",
)
```

```typescript
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

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

:::code-group
```bash
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>"
```

```python
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 value
```
:::

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.

## Related pages

- [API v1 is currently under development](./apis-coming-soon.md)
- [Credal | Documentation](../index.md)
- [Actions](./concepts-actions.md)
- [Getting Started](./getting-started-index.md)
- [Introduction](./getting-started-introduction.md)
- [Overview](./overview-overview.md)
- [Agent Builder](./platform-agent-builder.md)
- [Agents](./concepts-agents.md)
- [Quickstart](./getting-started-quickstart.md)
- [Service Accounts](./overview-service-accounts.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.