# List mailbox credentials

Returns every credential of a mailbox, revoked and expired ones included (secrets are never returned). Self-service: the mailbox's own bearer may read its own list.

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

### Path parameters

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

### Responses

**200** — List of credentials

`application/json` → object

- `credentials` (Credential[], required)
  - `createdAt` (integer <int64>, required) — Creation timestamp in epoch seconds
  - `expiresAt` (integer | null, required) — Expiration timestamp in epoch seconds, or null for no expiry
  - `id` (string, required) — Unique credential ULID
  - `kind` ("password" | "app_password", required) — Credential kind ('password' for main login, 'app_password' for client token)
  - `lastUsedAt` (integer | null, required) — Timestamp when credential was last used in epoch seconds, or null
  - `name` (string | null, required) — Descriptive name or label (e.g. 'Phone Mail App'), or null
  - `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
  - `revokedAt` (integer | null, required) — Timestamp when credential was revoked in epoch seconds, or null
  - `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)
  - `username` (string, required) — Login username or email address

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

`application/json` → ErrorBody

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

`application/json` → ErrorBody

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

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/identities/{identityId}/credentials' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

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

```ts
const result = await openemail.credentials.list(identityId)
```
