OAuth Setup

OAuth Setup

API v1 uses OAuth 2.0 with PKCE for authentication. If you’re new to OAuth, see OAuth 2.0 with PKCE for background on the protocol.

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.

2. Configure your environment

After registering your client, you’ll have a client ID and client secret. Configure your OAuth client with the following:

Credal supports OpenID Connect Discovery, so most OAuth libraries can auto-configure endpoints from the issuer URL.

When requesting authorization, include the scopes your application needs. The following scopes are available:

3. Authenticate and call the API

After completing the OAuth flow, pass the access token to the Credal SDK:

1
import { CredalClient } from "@credal/sdk";
2
3
const credal = new CredalClient({
4
  token: accessToken,
5
  environment: "https://app.credal.ai/api/v1",
6
});
7
8
const response = await credal.agents.sendMessage({
9
  agentId: "your-agent-id",
10
  conversation: { type: "new" },
11
  message: "Hello!",
12
});

Token refresh

Access tokens are short-lived. Use the refresh token from the initial authorization to obtain new access tokens when they expire. Refer to your OAuth library’s documentation for details on implementing token refresh.