# create()

Creates a new [API key](https://clerk.com/docs/guides/development/machine-auth/api-keys.md). Returns the created [`APIKey`](https://clerk.com/docs/reference/backend/types/backend-api-key.md) object.

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

## `CreateAPIKeyParams`

| Name                    | Type                             | Description                                                                              |
| ----------------------- | -------------------------------- | ---------------------------------------------------------------------------------------- |
| name                    | string                           | A descriptive name for the API key (e.g., "Production API Key", "Development Key").      |
| subject                 | string                           | The user ID (user\_xxx) or organization ID (org\_xxx) to associate the API key with.     |
| description?            | string | null                   | A longer description of what the API key is used for.                                    |
| scopes?                 | string[]                        | An array of scope strings that define what the API key can access.                       |
| claims?                 | Record<string, unknown> | null | Additional custom claims to store additional information about the API key.              |
| createdBy?              | string | null                   | The user ID of the user creating the API key (for audit purposes).                       |
| secondsUntilExpiration? | number | null                   | Number of seconds until the API key expires. Defaults to null (API key does not expire). |

## Example

> Using `clerkClient` varies based on the SDK you're using. Refer to the [overview](https://clerk.com/docs/reference/backend/overview.md) for usage details, including guidance on [how to access the `userId` and other properties](https://clerk.com/docs/reference/backend/overview.md#example-get-the-user-id-and-other-properties).

### Create a basic API key

```tsx
const userId = 'user_123'

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

### Create an API key with optional parameters

```tsx
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
})
```

> 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](https://clerk.com/docs/reference/backend-api/tag/api-keys/POST/api_keys){{ target: '_blank' }} for more information.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)