Skip to main content
Docs

create()

Creates a new API key.

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

CreateAPIKeyParams

  • Name
    name
    Type
    string
    Description

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

  • Name
    subject
    Type
    string
    Description

    The user ID (user_xxx) or organization ID (org_xxx) to associate the API key with.

  • Name
    description?
    Type
    string | null
    Description

    A longer description of what the API key is used for.

  • Name
    scopes?
    Type
    string[]
    Description

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

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

    A JavaScript object that can be used to store additional information about the API key.

  • Name
    createdBy?
    Type
    string | null
    Description

    The user ID of the user creating the API key (for audit purposes).

  • Name
    secondsUntilExpiration?
    Type
    number | null
    Description

    The number of seconds until the API key will expire. By default, the API key will not expire. API keys are typically long-lived tokens that don't expire, as expiring API keys would cause third-party services using them to break unexpectedly.

Example

Note

Using clerkClient varies based on your framework. Refer to the JS Backend SDK overview for usage details, including guidance on how to access the userId and other properties.

Basic API key creation

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

API key with optional parameters

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

Warning

The API key secret is only available in the response from create() and cannot be retrieved again. Make sure to store the secret securely immediately after creation.

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?
GitHubEdit on GitHub

Last updated on