Auth Configs
An auth config is a blueprint that defines how a toolkit authenticates across all your users. It specifies the authentication method, the scopes your tools can request, and which credentials Composio uses to run the OAuth or token flow.
A single auth config applies to every user who connects that toolkit. When a user authenticates against it, Composio creates a connected account that stores their tokens and links them to your user ID.
Each auth config defines:
- Auth scheme: OAuth2, API key, Bearer token, or Basic Auth
- Scopes: what your tools are allowed to do on the user's behalf
- Credentials: Composio's managed app, or your own OAuth client and secrets
Reach for a custom auth config when you need your own branding on consent screens, custom scopes, a dedicated rate-limit quota, or a custom toolkit instance. See managed vs custom auth for the decision and how Composio handles authentication for the full picture.
Auth schemes
The auth_scheme on an auth config determines how users authenticate to the toolkit. Composio supports four. The schemes available for a given toolkit come from the toolkit itself.
| Scheme | What it is | When it's used |
|---|---|---|
OAUTH2 | OAuth 2.0 authorization-code flow. The user authorizes through a hosted consent screen, and Composio stores and automatically refreshes the access and refresh tokens. | Most apps with user accounts (Gmail, GitHub, Slack, Notion, and so on). Uses Composio's managed OAuth app by default; bring your own for custom branding or scopes. |
API_KEY | A static API key the user provides. There's no OAuth flow: the key is stored on the connected account and sent on each request. | Services that authenticate with a key, such as SendGrid, Tavily, or PostHog. |
BEARER_TOKEN | A bearer access token you already hold (for example, from your own OAuth flow). Composio sends it as Authorization: Bearer <token> and does not refresh it, so you keep it current. | Bringing an existing OAuth or server-to-server token into Composio, or apps that issue long-lived tokens. |
BASIC | HTTP Basic authentication with a username and password. | Services that use Basic Auth. |
Most OAuth toolkits work out of the box with Composio managed auth. For the others you supply the credential fields. To choose or customize the scheme, see managed vs custom auth.
These endpoints use your project API key in the x-api-key header. Each auth config is addressed by its nanoid, and you can enable or disable one without deleting it.
Endpoints
| Endpoint | Quick Link |
|---|---|
POST /api/v3.1/auth_configs | Create new authentication configuration |
GET /api/v3.1/auth_configs | List authentication configurations with optional filters |
GET /api/v3.1/auth_configs/{nanoid} | Get single authentication configuration by ID |
PATCH /api/v3.1/auth_configs/{nanoid} | Update an authentication configuration |
DELETE /api/v3.1/auth_configs/{nanoid} | Delete an authentication configuration |
PATCH /api/v3.1/auth_configs/{nanoid}/{status} | Enable or disable an authentication configuration |