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, 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 object is of type APIKeyResource.

  • Name
    claims
    Type
    Record<string, any> | null
    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
    string | null
    Description

    The ID of the user that created the API key.

  • Name
    description
    Type
    string | null
    Description

    An optional description for the API key.

  • Name
    expiration
    Type
    Date | null
    Description

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

  • Name
    expired
    Type
    boolean
    Description

    Whether the API key is expired.

  • Name
    id
    Type
    string
    Description

    The unique identifier of the API key.

  • Name
    lastUsedAt
    Type
    Date | null
    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
    string | null
    Description

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

  • Name
    revoked
    Type
    boolean
    Description

    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

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.

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.

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.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub