Skip to main content

APIKeys object

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, that can be instantly revoked.

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.

Example

The APIKeys object is available on the Clerk object. Use the useClerk() hook to access the clerk object, as shown in the following example.

app/page.tsx
'use client'

import { useClerk } from '@clerk/nextjs'

export default function Page() {
  // Use the useClerk hook to access the clerk object
  const clerk = useClerk()

  // Access the APIKeys object
  const apiKeys = clerk.apiKeys

  return <pre>{JSON.stringify(apiKeys, null, 2)}</pre>
}

Properties

The APIKeys methods create, list, and revoke APIKeyResource objects. The properties below describe APIKeyResource.

  • Name
    claims
    Type
    null | Record<string, any>
    Description

    Custom claims associated with the API key, or null if none.

  • Name
    createdAt
    Type
    Date
    Description

    The date and time when the API key was created.

  • Name
    createdBy
    Type
    null | string
    Description

    The ID of the user that created the API key.

  • Name
    description
    Type
    null | string
    Description

    A description for the API key.

  • Name
    expiration
    Type
    null | Date
    Description

    The expiration date and time for the API key, or null if the key never expires.

  • Name
    expired
    Type
    boolean
    Description

    Indicates whether the API key has expired.

  • Name
    id
    Type
    string
    Description

    A unique identifier for the API key.

  • Name
    lastUsedAt
    Type
    null | Date
    Description

    The date and time when the API key was last used to authenticate a request, or null if it has never been used.

  • Name
    name
    Type
    string
    Description

    The name of the API key.

  • Name
    revocationReason
    Type
    null | string
    Description

    The reason the API key was revoked, or null if not revoked.

  • Name
    revoked
    Type
    boolean
    Description

    Indicates whether the API key has been revoked.

  • Name
    scopes
    Type
    string[]
    Description

    An array of scopes that define what the API key can access.

  • Name
    secret?
    Type
    string
    Description

    The API key secret. This property is only present in the response from create() and cannot be retrieved later.

  • Name
    subject
    Type
    string
    Description

    The user or organization ID that the API key is associated with.

  • Name
    type
    Type
    string
    Description

    The type of the API key.

  • Name
    updatedAt
    Type
    Date
    Description

    The date and time when the API key was last updated.

Methods

create()

Creates a new API key.

Returns an APIKeyResource object that includes the secret property.

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
    description?
    Type
    string
    Description

    The description of the API key.

  • Name
    name
    Type
    string
    Description

    The name of the API key.

  • Name
    secondsUntilExpiration?
    Type
    number
    Description

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

  • 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.

getAll()

Gets 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
    initialPage?
    Type
    number
    Description

    A number that specifies which page to fetch. For example, if initialPage is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to 1.

  • Name
    pageSize?
    Type
    number
    Description

    A number that specifies the maximum number of results to return per page. Defaults to 10.

  • Name
    query?
    Type
    string
    Description

    A search query to filter API keys by name.

  • 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.

reload()

Reloads the resource, which is useful when you want to access the latest user data after performing a mutation. To make the updated data immediately available, this method forces a session token refresh instead of waiting for the automatic refresh cycle that could temporarily retain stale information. Learn more about forcing a token refresh.

function reload(p?: ClerkResourceReloadParams): Promise<APIKeyResource>

ClerkResourceReloadParams

  • Name
    rotatingTokenNonce?
    Type
    string
    Description

    A nonce to use for rotating the user's token. Used in native application OAuth flows to allow the native client to update its JWT once despite changes in its rotating token.

revoke()

Revokes a given 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
    Description

    The reason for revoking the API key.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub