Skip to main content
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. 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.

List authentication configurations with optional filters

Retrieves all auth configs for your project. Auth configs define how users authenticate with external services (OAuth, API keys, etc.). Use filters to find configs for specific toolkits or to distinguish between Composio-managed and custom configurations.

Get single authentication configuration by ID

Retrieves detailed information about a specific authentication configuration using its unique identifier.

Create new authentication configuration

Creates a new auth config for a toolkit, allowing you to use your own OAuth credentials or API keys instead of Composio-managed authentication. This is required when you want to use custom OAuth apps (bring your own client ID/secret) or configure specific authentication parameters for a toolkit.

Update an authentication configuration

Modifies an existing authentication configuration with new credentials or other settings. Only specified fields will be updated.

Enable or disable an authentication configuration (DEPRECATED)

DEPRECATED: We are controlling the API surface and the dependencies between endpoints, and enabling or disabling an auth config is covered by existing endpoints. To stop new connections through an auth config, stop creating connected accounts with it; to remove it, delete it with `DELETE /api/v3/auth_configs/{nanoid}` (pass `?revoke_on_delete=true` to also revoke the upstream credentials of its connections). This endpoint still works for existing integrations but may be removed in a future release. It sets the auth config to ENABLED or DISABLED; disabled auth configs cannot be used for new connections.

Delete an authentication configuration

Deletes an authentication configuration. This operation cannot be undone. Pass `?revoke_on_delete=true` to also revoke the upstream credentials of every connection using this auth config.