Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | # Auth Configs API |
| 2 | |
| 3 | The `AuthConfigs` class provides methods to manage authentication configurations for toolkits. Auth configs define how authentication works for a particular toolkit, specifying the auth scheme (OAuth2, API Key, etc.) and other authentication-related details. |
| 4 | |
| 5 | ## Methods |
| 6 | |
| 7 | ### list(query?) |
| 8 | |
| 9 | Lists all auth configs based on provided filter criteria. |
| 10 | |
| 11 | ```typescript |
| 12 | // List all auth configs |
| 13 | const allAuthConfigs = await composio.authConfigs.list(); |
| 14 | |
| 15 | // List auth configs for a specific toolkit |
| 16 | const githubAuthConfigs = await composio.authConfigs.list({ |
| 17 | toolkit: 'github', |
| 18 | }); |
| 19 | |
| 20 | // Search auth configs by name or id and include disabled configs |
| 21 | const searchedAuthConfigs = await composio.authConfigs.list({ |
| 22 | search: 'github', |
| 23 | showDisabled: true, |
| 24 | }); |
| 25 | ``` |
| 26 | |
| 27 | **Parameters:** |
| 28 | |
| 29 | - `query` (AuthConfigListParams): Optional query parameters for filtering auth configs |
| 30 | |
| 31 | **Returns:** Promise<AuthConfigListResponse> - A paginated list of auth configs |
| 32 | |
| 33 | **Throws:** ValidationError if the query fails validation against the expected schema |
| 34 | |
| 35 | ### get(id) |
| 36 | |
| 37 | Retrieves a specific auth config by its ID. |
| 38 | |
| 39 | ```typescript |
| 40 | // Get an auth config by ID |
| 41 | const authConfig = await composio.authConfigs.get('auth_config_123'); |
| 42 | console.log(authConfig.name); // Name of the auth config |
| 43 | ``` |
| 44 | |
| 45 | **Parameters:** |
| 46 | |
| 47 | - `id` (string): The unique identifier of the auth config |
| 48 | |
| 49 | **Returns:** Promise<AuthConfigRetrieveResponse> - The auth config details |
| 50 | |
| 51 | **Throws:** ComposioAuthConfigNotFoundError if the auth config cannot be found |
| 52 | |
| 53 | ### create(toolkit, data) |
| 54 | |
| 55 | Creates a new auth config for a toolkit. |
| 56 | |
| 57 | ```typescript |
| 58 | // Create an auth config for GitHub |
| 59 | const authConfig = await composio.authConfigs.create('github', { |
| 60 | type: 'use_composio_managed_auth', |
| 61 | name: 'GitHub Auth Config', |
| 62 | }); |
| 63 | ``` |
| 64 | |
| 65 | **Parameters:** |
| 66 | |
| 67 | - `toolkit` (string): The slug of the toolkit to create an auth config for |
| 68 | - `data` (AuthConfigCreateParams): The parameters for creating the auth config |
| 69 | |
| 70 | **Returns:** Promise<AuthConfigCreateResponse> - The created auth config |
| 71 | |
| 72 | **Throws:** |
| 73 | |
| 74 | - ValidationError if the parameters fail validation |
| 75 | - ComposioToolNotFoundError if the toolkit cannot be found |
| 76 | |
| 77 | ### update(id, data) |
| 78 | |
| 79 | Updates an existing auth config. |
| 80 | |
| 81 | ```typescript |
| 82 | // Update a custom auth config with new credentials |
| 83 | const updatedAuthConfig = await composio.authConfigs.update('auth_config_123', { |
| 84 | type: 'custom', |
| 85 | credentials: { |
| 86 | client_id: 'new_client_id', |
| 87 | client_secret: 'new_client_secret', |
| 88 | }, |
| 89 | toolAccessConfig: { |
| 90 | toolsAvailableForExecution: ['GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER'], |
| 91 | }, |
| 92 | }); |
| 93 | |
| 94 | // Update a default auth config with new scopes |
| 95 | const updatedDefaultAuth = await composio.authConfigs.update('auth_config_456', { |
| 96 | type: 'default', |
| 97 | scopes: 'read:user,repo', |
| 98 | toolAccessConfig: { |
| 99 | toolsAvailableForExecution: ['GITHUB_GET_A_REPOSITORY', 'GITHUB_LIST_REPOSITORIES_FOR_A_USER'], |
| 100 | }, |
| 101 | }); |
| 102 | ``` |
| 103 | |
| 104 | **Parameters:** |
| 105 | |
| 106 | - `id` (string): The unique identifier of the auth config to update |
| 107 | - `data` (AuthConfigUpdateParams): The parameters for updating the auth config. Must be a discriminated union with either: |
| 108 | - `{ type: 'custom', credentials: Record<string, unknown>, toolAccessConfig?: {...} }` |
| 109 | - `{ type: 'default', scopes: string, toolAccessConfig?: {...} }` |
| 110 | |
| 111 | **Returns:** Promise<AuthConfigUpdateResponse> - The updated auth config |
| 112 | |
| 113 | **Throws:** |
| 114 | |
| 115 | - ValidationError if the update parameters are invalid |
| 116 | - ComposioAuthConfigNotFoundError if the auth config cannot be found |
| 117 | |
| 118 | ### delete(id) |
| 119 | |
| 120 | Deletes an auth config. |
| 121 | |
| 122 | ```typescript |
| 123 | // Delete an auth config |
| 124 | await composio.authConfigs.delete('auth_config_123'); |
| 125 | ``` |
| 126 | |
| 127 | **Parameters:** |
| 128 | |
| 129 | - `id` (string): The unique identifier of the auth config to delete |
| 130 | |
| 131 | **Returns:** Promise<AuthConfigDeleteResponse> - The deletion response |
| 132 | |
| 133 | **Throws:** Error if the auth config doesn't exist or cannot be deleted |
| 134 | |
| 135 | ## Types |
| 136 | |
| 137 | ### AuthConfigListParams |
| 138 | |
| 139 | ```typescript |
| 140 | interface AuthConfigListParams { |
| 141 | cursor?: string; // Pagination cursor |
| 142 | limit?: number; // Limit the number of results |
| 143 | search?: string; // Search auth configs by name or id |
| 144 | showDisabled?: boolean; // Include disabled auth configs |
| 145 | toolkit?: string; // Filter by toolkit slug |
| 146 | isComposioManaged?: boolean; // Filter by Composio-managed auth configs |
| 147 | } |
| 148 | ``` |
| 149 | |
| 150 | ### AuthConfigListResponse |
| 151 | |
| 152 | ```typescript |
| 153 | interface AuthConfigListResponse { |
| 154 | items: AuthConfigRetrieveResponse[]; // List of auth configs |
| 155 | nextCursor: string | null; // Pagination cursor |
| 156 | totalPages: number; // Total number of pages |
| 157 | } |
| 158 | ``` |
| 159 | |
| 160 | ### AuthConfigRetrieveResponse |
| 161 | |
| 162 | ```typescript |
| 163 | interface AuthConfigRetrieveResponse { |
| 164 | id: string; // Auth config ID |
| 165 | name: string; // Name of the auth config |
| 166 | type: AuthConfigType; // Type of auth config |
| 167 | toolkit: { |
| 168 | // Associated toolkit |
| 169 | id: string; // Toolkit ID |
| 170 | slug: string; // Toolkit slug |
| 171 | name: string; // Toolkit name |
| 172 | }; |
| 173 | authScheme: AuthSchemeType; // Auth scheme (e.g., 'oauth2', 'api_key') |
| 174 | isDisabled: boolean; // Whether the auth config is disabled |
| 175 | fields: Record<string, unknown>; // Configuration fields |
| 176 | meta: Record<string, unknown>; // Additional metadata |
| 177 | createdAt: string; // Creation timestamp |
| 178 | updatedAt: string; // Last update timestamp |
| 179 | } |
| 180 | ``` |
| 181 | |
| 182 | ### AuthConfigCreateParams |
| 183 | |
| 184 | ```typescript |
| 185 | interface AuthConfigCreateParams { |
| 186 | type: AuthConfigType; // Type of auth config |
| 187 | name: string; // Name of the auth config |
| 188 | fields?: Record<string, unknown>; // Configuration fields |
| 189 | } |
| 190 | ``` |
| 191 | |
| 192 | ### AuthConfigUpdateParams |
| 193 | |
| 194 | ```typescript |
| 195 | // Discriminated union type for updating auth configs |
| 196 | type AuthConfigUpdateParams = |
| 197 | | { |
| 198 | type: 'custom'; |
| 199 | credentials: Record<string, string | number | boolean | unknown>; |
| 200 | toolAccessConfig?: { |
| 201 | toolsAvailableForExecution?: string[]; |
| 202 | toolsForConnectedAccountCreation?: string[]; |
| 203 | }; |
| 204 | /** @deprecated Use toolAccessConfig instead */ |
| 205 | restrictToFollowingTools?: string[]; |
| 206 | } |
| 207 | | { |
| 208 | type: 'default'; |
| 209 | scopes: string; |
| 210 | toolAccessConfig?: { |
| 211 | toolsAvailableForExecution?: string[]; |
| 212 | toolsForConnectedAccountCreation?: string[]; |
| 213 | }; |
| 214 | /** @deprecated Use toolAccessConfig instead */ |
| 215 | restrictToFollowingTools?: string[]; |
| 216 | }; |
| 217 | ``` |
| 218 | |
| 219 | ### AuthConfigType |
| 220 | |
| 221 | Auth config types are defined as an enum: |
| 222 | |
| 223 | ```typescript |
| 224 | enum AuthConfigTypes { |
| 225 | USE_COMPOSIO_MANAGED_AUTH = 'use_composio_managed_auth', |
| 226 | SERVICE_CONNECTION = 'service_connection', |
| 227 | USER_CREDENTIALS = 'user_credentials', |
| 228 | CUSTOM_AUTH = 'custom_auth', |
| 229 | NO_AUTH = 'no_auth', |
| 230 | } |
| 231 | ``` |
| 232 | |
| 233 | ### AuthSchemeType |
| 234 | |
| 235 | Auth scheme types are defined as an enum: |
| 236 | |
| 237 | ```typescript |
| 238 | enum AuthSchemeTypes { |
| 239 | OAUTH2 = 'oauth2', |
| 240 | API_KEY = 'api_key', |
| 241 | BASIC_AUTH = 'basic_auth', |
| 242 | CUSTOM = 'custom', |
| 243 | NO_AUTH = 'no_auth', |
| 244 | } |
| 245 | ``` |