Skip to main content

create()

Note

Looking for the and you use to connect your own app to Clerk? Those are different from the API keys described here. You can copy them from the API keys page in the Clerk Dashboard, or learn more in the Clerk environment variables reference.

Creates a new API key for the given user or Organization.

Returns the created APIKey object.

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

CreateAPIKeyParams

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

    Custom claims to store additional information about the API key.

  • Name
    createdBy?
    Type
    string | null
    Description

    The user ID of the user who created the API key.

  • Name
    description?
    Type
    string | null
    Description

    The description of the API key.

  • Name
    name
    Type
    string
    Description

    A descriptive name for the API key (e.g., "Production API Key", "Development Key").

  • Name
    scopes?
    Type
    string[]
    Description

    Scopes to limit the API key's access to specific resources.

  • Name
    secondsUntilExpiration?
    Type
    number | null
    Description

    The number of seconds until the API key expires. Defaults to null (never expires).

  • Name
    subject
    Type
    string
    Description

    The user or Organization ID to associate the API key with.

Usage

Note

Using clerkClient varies based on the SDK you're using. Refer to the overview for usage details, including guidance on how to access the userId and other properties.

Create a basic API key

const userId = 'user_123'

const apiKey = await clerkClient.apiKeys.create({
  name: 'My API Key',
  subject: userId,
})

Create an API key with optional parameters

const userId = 'user_123'

const apiKey = await clerkClient.apiKeys.create({
  name: 'Production API Key',
  subject: userId,
  description: 'API key for accessing my application',
  scopes: ['read:users', 'write:users'],
  secondsUntilExpiration: 86400, // expires in 24 hours
})

Backend API (BAPI) endpoint

This method in the SDK is a wrapper around the BAPI endpoint POST/api_keys. See the BAPI reference for more information.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub