# apiKeys.create

Create API key.

Creates an API key and returns the plaintext secret token once.

```ts
openemail.apiKeys.create(
  body: ApiKeysCreateBody,
  options?: CallOptions,
): ApiPromise<ApiKeyCreated>
```

It calls `POST /api-keys`: [Create API key](/docs/api/credentials/post_ApiKeyCreate) in the API reference.

## Example

```ts
const apiKeyCreated = await openemail.apiKeys.create({ name: 'Ada' })
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `body` | [`ApiKeysCreateBody`](#apikeyscreatebody) | The request's body. |

## Options

It takes no options of its own. Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`ApiKeyCreated`](/docs/sdks/typescript/types/api-key-created). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.withResponse()` gives the same with the `Response` it came in, for its headers.

## Errors

| Status | What it means |
| --- | --- |
| `400` | validation_failed, account_id_required, unknown_account, system_key_unexpirable, system_key_unscopable, invalid_domain (a `domains` entry is not a bare domain name; `domain` names it), or unknown_domain (a `domains` entry the target account does not hold; `domain` names it — identical for a missing and a foreign domain) |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `403` | system_credentials_required or cannot_mint_for_other_account |
| `413` | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
| `503` | temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description) |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

### ApiKeysCreateBody

```ts
/** The body of `apiKeys.create`. */
type ApiKeysCreateBody = {
  /** Account ULID to associate key with (required for account role) */
  accountId?: string
  /** Scope this key to these domains (bare lowercase names the owning account holds — an unknown or foreign one answers 400 unknown_domain naming it). A scoped key is an ACCOUNT key wearing a restriction: it reaches the directory of these domains (routes, patterns, DNS, branding, hostnames, webhooks) and the mailboxes with an address on them, and nothing whose subject is the account itself (403 account_credentials_required), nor JMAP. Delegation within one account, not tenancy — every domain still shares the account's caps, storage pool and bill. Omit for full account authority. Refused on system keys (400 system_key_unscopable); fixed for the key's life (revoke and re-mint to change). */
  domains?: string[]
  /** Seconds of disuse after which this key stops authenticating, measured from last use (or from creation while it has never been used). Omit for a key that never lapses, which is the default and what every key had before. Refused on system keys. */
  idleTtlS?: number
  /** Display metadata for what this key is ('cli' for one the browser login minted). NEVER an authorization input — the caller sets it, so nothing may branch on it; it exists so a keys list can identify a row without matching on a name the owner can change. */
  kind?: string
  /** System callers only: an infrastructure-held key, hidden from the owning account */
  managed?: boolean
  /** Human-readable label for this API key */
  name: string
  /** Role level ('account' for tenant-scoped, 'system' for cluster-wide admin) */
  role?: ('system' | 'account')
  /** System callers only: frontend service surface for meter attribution */
  surface?: ('rest' | 'jmap' | 'dav' | 'gateway' | 'webmail' | 'console' | 'mcp')
}
```

It names these types of the API, each on a page of its own: [`ApiKeyCreated`](/docs/sdks/typescript/types/api-key-created).
