api-key/operations

21 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Creating API keys with specific configId

When creating an API key with auth.api.createApiKey(), specify which configuration to use via the configId parameter in the body. The generated key will have the prefix associated with that configuration. Example: configId: "public" generates pk_ prefix, configId: "secret" generates sk_ prefix.

configId requirement for get, update, delete operations

For get, update, and delete API key operations, you must pass the same configId that the key was created with. The verify operation resolves the key's own configuration, so it only needs configId when a configuration differs from the default in storage or hashing.

Filtering API keys by configId when listing

When listing API keys using authClient.apiKey.list(), you can filter by configId in the query parameter. Example: authClient.apiKey.list({ query: { configId: "public" } }) lists only public keys.

createApiKey endpoint path and method

The endpoint to create an API key is POST /api-key/create.

createApiKey parameters reference

The createApiKey endpoint accepts the following parameters: configId (optional, string, default: default configuration), name (optional, string, default: 'project-api-key'), expiresIn (optional, number in seconds, default: 60 * 60 * 24 * 7), userId (server-only, string, required for user-owned keys when not using session headers, default: 'user-id'), organizationId (optional, string, required for organization-owned keys when config has `references: 'organization'`, default: 'org-id'), prefix (optional, string, default: 'project-api-key'), remaining (server-only, number, default: 100), metadata (optional, any or null, default: { someKey: 'someValue' }), refillAmount (server-only, number, default: 100), refillInterval (server-only, number in milliseconds, default: 1000), rateLimitTimeWindow (server-only, number in milliseconds, default: 1000), rateLimitMax (server-only, number, default: 100), rateLimitEnabled (server-only, boolean, default: true), and permissions (server-only, Record<string, string[]>). The endpoint returns the ApiKey object including the key value, or throws an APIError on failure.

verifyApiKey endpoint path and method

The endpoint to verify an API key is POST /api-key/verify, and it is server-only.

verifyApiKey parameters and result

The verifyApiKey endpoint accepts: configId (optional, string, scopes verification to a specific configuration; when omitted, the key is validated against its own configuration), key (required, string, the key to verify, example: 'your_api_key_here'), and permissions (optional, Record<string, string[]>, permissions to check). The endpoint returns an object with: valid (boolean), error (object with message and code strings, or null), and key (Omit<ApiKey, 'key'> or null).

getApiKey endpoint path and method

The endpoint to get an API key is GET /api-key/get, and it requires a session.

getApiKey parameters and result

The getApiKey endpoint accepts: configId (optional, string, default: default configuration, used for the API key lookup), and id (required, string, the API key ID, example: 'some-api-key-id'). The endpoint returns everything about the API key details except for the key value itself (Omit<ApiKey, 'key'>), or throws an APIError on failure.

updateApiKey endpoint path and method

The endpoint to update an API key is POST /api-key/update.

updateApiKey parameters and result

The updateApiKey endpoint accepts: configId (optional, string, default: default configuration), keyId (required, string, the API key ID to update, example: 'some-api-key-id'), userId (server-only, string, the user ID which the API key belongs to, example: 'some-user-id'), name (optional, string, the name of the key, example: 'some-api-key-name'), enabled (server-only, boolean, default: true, whether the API key is enabled), remaining (server-only, number, default: 100, the number of remaining requests), refillAmount (server-only, number, default: 100), refillInterval (server-only, number in milliseconds, default: 1000), metadata (server-only, any or null, default: { 'key': 'value' }), expiresIn (server-only, number in seconds, default: 60 * 60 * 24 * 7), rateLimitEnabled (server-only, boolean, default: true), rateLimitTimeWindow (server-only, number in milliseconds, default: 1000), rateLimitMax (server-only, number, default: 100), and permissions (server-only, Record<string, string[]>). Returns the API key details except for the key value itself (Omit<ApiKey, 'key'>), or throws an APIError on failure.

deleteApiKey endpoint path and method

The endpoint to delete an API key is POST /api-key/delete, and it requires a session. This endpoint checks if the user's ID matches the key owner before deletion. To delete a key without these checks, use an ORM to directly mutate the database instead.

deleteApiKey parameters and result

The deleteApiKey endpoint accepts: configId (optional, string, default: default configuration, used for the API key lookup), and keyId (required, string, the API key ID to delete, example: 'some-api-key-id'). Returns an object with: success (boolean), or throws an APIError on failure.

listApiKeys endpoint path and method

The endpoint to list API keys is GET /api-key/list, and it requires a session.

listApiKeys parameters and result

The listApiKeys endpoint accepts: configId (optional, string, filter by configuration ID; if not provided, returns keys from all configurations), organizationId (optional, string, to list organization-owned keys; if not provided, returns user-owned keys for the current session user), limit (optional, number, the number of API keys to return), offset (optional, number, the offset to start from for pagination), sortBy (optional, string, the field to sort by, e.g., 'createdAt', 'name', 'expiresAt'), and sortDirection (optional, 'asc' or 'desc'). Returns a paginated response object with: apiKeys (array of Omit<ApiKey, 'key'>), total (number), limit (optional, number), and offset (optional, number). Throws an APIError on failure.

listApiKeys pagination and sorting examples

Get first 10 API keys: await authClient.apiKey.list({ query: { limit: 10 } }). Get second page with 10 items per page: await authClient.apiKey.list({ query: { limit: 10, offset: 10 } }). Sort by creation date newest first: await authClient.apiKey.list({ query: { sortBy: 'createdAt', sortDirection: 'desc' } }). Combined pagination and sorting: await authClient.apiKey.list({ query: { limit: 20, offset: 0, sortBy: 'name', sortDirection: 'asc' } }). List organization-owned keys: await authClient.apiKey.list({ query: { organizationId: 'org_123' } }). List organization keys with specific config: await authClient.apiKey.list({ query: { organizationId: 'org_123', configId: 'public' } }).

deleteAllExpiredApiKeys endpoint path and method

The endpoint to delete all expired API keys is POST /api-key/delete-all-expired-api-keys, and it is server-only.

Expired API keys automatic deletion behavior

Expired API keys are automatically deleted every time any apiKey plugin endpoints are called, however these deletions are rate-limited to a 10 second cooldown on each call to prevent multiple database calls.

Creating API Key with permissions

When creating an API key, you can specify custom permissions by calling auth.api.createApiKey with body containing name, permissions object, and userId. Example: const apiKey = await auth.api.createApiKey({ body: { name: "My API Key", permissions: { files: ["read", "write"], users: ["read"] }, userId: "userId" } });

Verifying API Key with required permissions

When verifying an API key, you can check if it has the required permissions by calling auth.api.verifyApiKey with body containing the key string and permissions object. The result has a valid property. Example: const result = await auth.api.verifyApiKey({ body: { key: "your_api_key_here", permissions: { files: ["read"] } } }); if (result.valid) { /* API key is valid and has required permissions */ }

Updating API Key permissions

You can update the permissions of an existing API key by calling auth.api.updateApiKey with body containing keyId and permissions object, and passing user headers. Example: const apiKey = await auth.api.updateApiKey({ body: { keyId: existingApiKeyId, permissions: { files: ["read", "write", "delete"], users: ["read", "write"] } }, headers: user_headers });

Give your agent this brain