# Create mailbox credential

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

## `POST /api/v1/identities/{identityId}/credentials`

### Path parameters

- `identityId` (string, required) — Mailbox identity ULID

### Request body (required)

`application/json`

- _option 1: object_
  - `kind` ("password", required)
  - `password` (string, required, 8–1024 chars)
  - `name` (string, max 128 chars)
  - `scope` ("full") — A login password is always 'full'; any other value is refused
  - `username` (string, 3–320 chars)
- _option 2: object_
  - `kind` ("app_password", required)
  - `currentPassword` (string, max 1024 chars) — 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)
  - `expiresInSeconds` (integer, ≥ 60, ≤ 31536000) — 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)
  - `name` (string, max 128 chars)
  - `permittedRecipients` (array | null, max 64 items) — 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
  - `scope` ("read" | "write" | "send" | "full") — 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
  - `surface` ("rest" | "jmap" | "dav" | "gateway" | "webmail" | "console" | "mcp") — 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
  - `username` (string, 3–320 chars)

### Responses

**200** — Created credential (app_password secret is shown only once in this response)

`application/json` → CredentialCreated

- _option 1: object_
  - `id` (string, required) — Credential ULID
  - `kind` ("password", required) — Standard password
  - `name` (string | null, required) — Optional credential label
  - `username` (string, required) — Username or email address
- _option 2: object_
  - `expiresAt` (integer | null, required) — Expiration timestamp in epoch seconds, or null for no expiry
  - `id` (string, required) — Credential ULID
  - `kind` ("app_password", required) — App-specific password
  - `name` (string | null, required) — Optional credential label
  - `permittedRecipients` (array | null, required) — The credential's OWN outbound recipient allowlist (exact addresses or `*@domain`), intersected with the identity's: both must permit. null = none of its own. Only a 'send' credential carries one
  - `scope` ("read" | "write" | "send" | "full", required) — The credential's scope, a ladder: 'read' (list and read mail — nothing that leaves a trace), 'write' (also mark, file, label and trash — everything the store can undo), 'send' (also submit mail), 'full' (also permanent deletion, every settings and credential route, PIM collection lifecycle and sharing — the human's own session, and the default)
  - `token` (string, required) — Plaintext app password secret (returned once only at creation)
  - `username` (string, required) — Username or email address

**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)

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**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)

`application/json` → ErrorBody

**404** — Mailbox not found or not accessible to this principal

`application/json` → ErrorBody

**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)

`application/json` → ErrorBody

**413** — too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing

`application/json` → ErrorBody

**429** — rate_limited — too many self-service attempts

`application/json` → ErrorBody

**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

`application/json` → ErrorBody

### Example request

```bash
curl -X POST 'https://api.open.email/api/v1/identities/{identityId}/credentials' \
  -H 'Authorization: Bearer oek_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "password",
    "password": "string"
  }'
```

## TypeScript SDK

[`openemail.credentials.create`](/docs/sdks/typescript/credentials/create)

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