Skip to main content
Docs

APIKeys object

Warning

API keys is currently in beta. The API may change before general availability.

The APIKeys object provides methods for managing API keys that allow your application's users to grant third-party services programmatic access to your application's API endpoints on their behalf. API keys are long-lived, opaque tokens that can be instantly revoked.

To use these methods, you must access them through the Clerk object: clerk.apiKeys.

Note

If a subject parameter is not provided, the methods will automatically use the ID if available, otherwise they will use the current User ID.

Methods

getAll()

Retrieves a paginated list of API keys for the current user or organization. Returns a ClerkPaginatedResponse of APIKeyResource objects.

function getAll(params?: GetAPIKeysParams): Promise<ClerkPaginatedResponse<APIKeyResource>>

GetAPIKeysParams

  • Name
    subject?
    Type
    string
    Description

    The user or organization ID to query API keys by. If not provided, defaults to the , then the current User.

  • Name
    query?
    Type
    string
    Description

    A search query to filter API keys by name.

  • Name
    initialPage?
    Type
    number
    Description

    A number that can be used to skip the first n-1 pages. For example, if initialPage is set to 10, it will skip the first 9 pages and will fetch the 10th page.

  • Name
    pageSize?
    Type
    number
    Description

    A number that indicates the maximum number of results that should be returned for a specific page.

Example

await clerk.apiKeys.getAll()

create()

Creates a new API key. Returns an APIKeyResource object that includes the secret property. The secret is only available in the response from create() and cannot be retrieved later.

Warning

Make sure to store the API key secret immediately after creation, as it will not be available again.

function create(params: CreateAPIKeyParams): Promise<APIKeyResource>

CreateAPIKeyParams

  • Name
    name
    Type
    string
    Description

    The name of the API key.

  • Name
    subject?
    Type
    string
    Description

    The user or organization ID to associate the API key with. If not provided, defaults to the , then the current User.

  • Name
    secondsUntilExpiration?
    Type
    number | null
    Description

    The number of seconds until the API key expires. Set to null or omit to create a key that never expires.

  • Name
    description?
    Type
    string | null
    Description

    An optional description for the API key.

Example

const apiKey = await clerk.apiKeys.create({
  name: 'My API Key',
  secondsUntilExpiration: 86400, // 24 hours
  description: 'API key for third-party service',
})

// Store the secret immediately
console.log('API Key Secret:', apiKey.secret)

revoke()

Revokes an API key by ID. Returns an APIKeyResource object.

function revoke(params: RevokeAPIKeyParams): Promise<APIKeyResource>

RevokeAPIKeyParams

  • Name
    apiKeyID
    Type
    string
    Description

    The ID of the API key to revoke.

  • Name
    revocationReason?
    Type
    string | null
    Description

    An optional reason for revoking the API key.

Example

await clerk.apiKeys.revoke({
  apiKeyID: 'ak_xxx',
  revocationReason: 'No longer needed',
})

Feedback

What did you think of this content?
GitHubEdit on GitHub

Last updated on