# credentials.create

Create mailbox credential.

Creates an IMAP login password or generates a scoped API app password for a mailbox.

```ts
openemail.credentials.create(
  identityId: string,
  body: CredentialsCreateBody,
  options?: CallOptions,
): ApiPromise<CredentialCreated>
```

It calls `POST /identities/{identityId}/credentials`: [Create mailbox credential](/docs/api/credentials/post_CredentialCreate) in the API reference.

## Example

```ts
const credentialCreated = await openemail.credentials.create(identityId, { kind: 'password', password: '…' })
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `identityId` | `string` | Mailbox identity ULID. The path's `{identityId}`. |
| `body` | [`CredentialsCreateBody`](#credentialscreatebody) | 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, [`CredentialCreated`](/docs/sdks/typescript/types/credential-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, username_required (the identity has no address for the username to default to, as one created withoutAddress has none: name it), invalid_address (D2: an address username must be an ASCII local part on an A-label domain), invalid_username (D2: a bare username must be printable ASCII with no whitespace), username_not_mailbox_address, username_not_in_scope (a DOMAIN-SCOPED api key may only mint a credential whose username is on one of its domains, migration 0078; `domain` names the refused one), permitted_recipients_requires_send (a recipient list on a credential whose scope is not 'send'), or password_required (the mailbox's own bearer sent no currentPassword) |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `403` | invalid_password (the mailbox's own bearer proved the wrong password), or account_credentials_required (a mailbox bearer asked for a login password: admin only; or a DOMAIN-SCOPED api key named a mailbox that is also routed on a domain outside its scope — a credential outlives the key that minted it, so minting one needs authority over every domain the mailbox serves) |
| `404` | Mailbox not found or not accessible to this principal |
| `409` | no_password_credential — the mailbox has no login password to prove, so it cannot self-serve; username_taken: a username that is not an address, already another identity's (under the objects directory) |
| `413` | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
| `429` | rate_limited — too many self-service attempts |
| `503` | temporary_failure: the login index could not take the claim, or the identity could not vouch for itself just now; retry after the Retry-After window |

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

### CredentialsCreateBody

```ts
/** The body of `credentials.create`. */
type CredentialsCreateBody = CredentialsCreateBodyPassword | CredentialsCreateBodyAppPassword
```

### CredentialsCreateBodyPassword

```ts
/** The API's `CredentialsCreateBodyPassword`, as the document describes it. */
type CredentialsCreateBodyPassword = {
  kind: 'password'
  name?: string
  password: string
  /** A login password is always 'full'; any other value is refused */
  scope?: 'full'
  username?: string
}
```

### CredentialsCreateBodyAppPassword

```ts
/** The API's `CredentialsCreateBodyAppPassword`, as the document describes it. */
type CredentialsCreateBodyAppPassword = {
  /** Required when the caller is the mailbox's OWN bearer (self-service), ignored for account and system callers: the mailbox's current login password, re-proved because an app password outlives the session that mints it. Refused as password_required (400), invalid_password (403) or no_password_credential (409) */
  currentPassword?: string
  /** Lifetime in seconds. The credential stops authenticating once it elapses: for a client minting one per browser session, so a closed tab cannot leave a permanently valid key behind. Omit for a credential that never expires (the default, and what a mail client wants) */
  expiresInSeconds?: number
  kind: 'app_password'
  name?: string
  /** The credential's OWN outbound recipient allowlist (exact addresses or `*@domain`), INTERSECTED with the identity's: both must permit. Accepted only with scope 'send' (400 permitted_recipients_requires_send otherwise); `[]` means this credential may send to nobody. At most 64 entries of at most 320 characters each (400 validation_failed otherwise). Omit or null for no list of its own */
  permittedRecipients?: string[] | null
  /** The credential's SCOPE (design D50), a ladder — 'read': list and read mail, nothing that leaves a trace; 'write': also mark, file, label and trash (everything the store undoes for 14 days); 'send': also submit mail; 'full' (the default): also permanent deletion, every settings route (rules, Sieve, vacation, prefs, forwarding, shares, retention, pickups, webhooks, credentials — reads included), PIM collection lifecycle and sharing. A call outside the scope answers 403 credential_scope naming the rung it needs. The bound for an agent token: mint 'write' for an assistant that reads and files, 'send' with permittedRecipients for one that may write to named people, and never 'full' for a program */
  scope?: ('read' | 'write' | 'send' | 'full')
  /** System callers only, and IGNORED for anyone else: which frontend this session credential belongs to, recorded on every API-request meter row it produces. The webmail BFF declares `webmail` when it mints a per-session password; a customer's own app password carries nothing, which is what keeps the two distinguishable */
  surface?: ('rest' | 'jmap' | 'dav' | 'gateway' | 'webmail' | 'console' | 'mcp')
  username?: string
}
```

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