Using API keys
Clerk's API keys feature allows your application's users to create API keys that can delegate access to your application's API on their behalf. API keys are typically long-lived tokens associated with a user or organization that provide access to a set of API endpoints for third-party services.
For example, imagine you're building an application like ChatGPT and you want developers on your platform to retrieve their recent conversations. You could let them generate API keys that are tied to their individual user accounts, giving them access only to their own chats. In this case, the API key would be scoped to a specific user. API keys can also be scoped to organizations or have granular scopes, such as allowing a key to read chats but not create new ones.
This guide demonstrates how to create API keys, list them, use them to authenticate requests, and revoke them when needed.
Pricing
Before getting started, it's important to note that API keys will be a paid feature. They are currently free to use while in beta, but will be charged based on usage after the beta period comes to an end. The pricing will be as follows:
$0.001per key creation.$0.0001per key verification.
There will be usage stats and monitoring available in the Clerk Dashboard before the beta period comes to an end to make it easy to understand your usage and what you're being charged.
Prerequisites
Before you can use API keys in your application, you must enable them in the Clerk Dashboard:
- In the Clerk Dashboard, navigate to the API keys page.
- Select Enable API keys.
- Select the option that you need depending on your use case: Enable User API keys, Enable Organization API keys, or both.
- Select Enable.
Enabling your users to create API keys via Clerk's UI components
Clerk provides UI components that you can drop into your application to support your users in generating and managing API keys. You can integrate these components into your application's interface, or create your own custom logic for API key management using JS Backend SDK methods.
If you're using Clerk's <UserProfile /> or <OrganizationProfile /> components and have enabled API keys in the Clerk Dashboard, an API Keys tab will automatically appear in those profile components. This tab will allow your users to create, view, and revoke API keys, without writing any additional custom code on your end.
If you'd prefer to hide the API Keys tab in the user or organization profile components, you can do so by passing a prop to the component, as such:
<UserProfile apiKeysProps={{ hide: true }} /><OrganizationProfile apiKeysProps={{ hide: true }} /><UserButton userProfileProps={{ apiKeysProps: { hide: true } }} />It's also possible to render the <APIKeys /> component directly if you want to embed the API key management UI within your own application's interface.
Using API keys in requests
Once you have an API key, you can use it to authenticate requests to your application's API. The API key should be sent as a Bearer token in the Authorization header:
await fetch('https://your-api.com/users', {
method: 'GET',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${apiKey}`,
},
})On your backend, you can verify the API key using Clerk's SDKs. See the verifying API keys guide for framework-specific examples.
Using API keys via Clerk's SDKs
If you would like to create, list, and revoke API keys programmatically on the server side, you can use Clerk's Backend SDKs. This guide uses the JS Backend SDK to demonstrate usage, but please note that the API keys feature is available in all of Clerk's Backend SDKs.
Creating API keys
To create an API key, call the create() method:
const apiKey = await clerkClient.apiKeys.create({
name: 'My API Key',
subject: 'user_xxx', // or 'org_xxx' for organization API keys
description: 'API key for accessing my application', // optional
scopes: ['read:users', 'write:users'], // optional
secondsUntilExpiration: 86400, // optional: expires in 24 hours
})The method returns an object containing the API key details, including the secret property with the actual API key value:
{
"id": "ak_xxx",
"name": "My API Key",
"description": "API key for accessing my application",
"subject": "user_xxx",
"scopes": ["read:users", "write:users"],
"claims": null,
"revoked": false,
"revocationReason": null,
"expired": false,
"expiration": 1754942036732,
"createdAt": 1754938436732,
"updatedAt": 1754938436732,
"createdBy": "user_xxx",
"secret": "ak_xxx"
}Required parameters
name- A descriptive name for the API key (e.g., "Production API Key", "Development Key").subject- The user ID (user_xxx) or organization ID (org_xxx) to associate the API key with.
Optional parameters
description- A longer description of what the API key is used for.scopes- An array of scope strings that define what the API key can access.claims- A JavaScript object that can be used to store additional information about the API key.createdBy- The user ID of the user creating the API key (for audit purposes).secondsUntilExpiration- The number of seconds until the API key expires. By default, API keys never expire. They are typically long-lived tokens since automatic expiration could cause third-party services using them to break unexpectedly. Instead, API keys can be instantly revoked if there is a security issue - this is possible because they are opaque tokens rather than JSON Web Tokens (JWTs).
Listing API keys
To list API keys, call the list() method:
const apiKeys = await clerkClient.apiKeys.list({
subject: 'user_xxx', // Filter by user or organization ID
includeInvalid: false, // Whether to include revoked or expired keys
})The method returns a paginated response with API key objects (without secrets):
{
"data": [
{
"id": "ak_xxx",
"name": "My API Key",
"description": "API key for accessing my application",
"subject": "user_xxx",
"scopes": ["read:users"],
"revoked": false,
"expired": false,
"expiration": 1754942036732,
"createdAt": 1754938436732,
"updatedAt": 1754938436732
}
],
"totalCount": 1
}Verifying API keys
To verify an API key secret, call the verify() method:
const apiKey = await clerkClient.apiKeys.verify(secret)If the API key is valid, the method will return the API key object with its properties. If the API key is invalid, revoked, or expired, the method will throw an error.
The following example demonstrates how to handle verification errors:
import { isClerkAPIResponseError } from '@clerk/shared/error'
try {
const apiKey = await clerkClient.apiKeys.verify(secret)
// API key is valid, proceed with the request
} catch (error) {
if (isClerkAPIResponseError(error)) {
console.error(error.errors[0]?.message)
}
throw error
}To revoke an API key, call the revoke() method:
await clerkClient.apiKeys.revoke({
apiKeyId: apiKey.id,
revocationReason: 'Key compromised', // optional, for your records
})This will revoke the API key and prevent it from being used to authenticate any future requests. The API key will remain in your list but will be marked as revoked.
Feedback
Last updated on