> ## Documentation Index
> Fetch the complete documentation index at: https://docs.drin.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an API key

> POST /v1/api-keys — mint a new API key. The secret is returned exactly once.

Mint a new key. The full secret is returned once, in this response only — store it immediately. Afterwards only its prefix and last four characters are visible.

**`POST /v1/api-keys`**

Keys are account (tenant) resources. By default a key is account-wide; pass `senderId` to lock it to a single project. The wire form of the secret is `<keyPrefix>_<secret>` — send it whole as the bearer token.

## Body parameters

<ParamField body="name" type="string" required>
  A label to recognize the key by, shown in the dashboard.
</ParamField>

<ParamField body="senderId" type="string">
  Scope the key to one project. Must be a project in your account. Omit for an account-wide key (callers then name the project per-request with the `X-Drin-Product` header).
</ParamField>

<ParamField body="scopes" type="string[]">
  Permission scopes to grant (e.g. `emails:send`). Omit for a key with the account's default permissions.
</ParamField>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.drin.run/v1/api-keys \
    -H "Authorization: Bearer $DRIN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "production",
      "scopes": ["emails:send"]
    }'
  ```

  ```typescript Node.js theme={null}
  import { DrinClient } from "@drin00/sdk";

  const drin = new DrinClient({ apiKey: process.env.DRIN_API_KEY });

  const key = await drin.apiKeys.create({
    name: "production",
    scopes: ["emails:send"],
  });

  // Store key.secret now — it is never shown again.
  console.log(key.secret); // "drin_a1b2c3d4e5f6_9f8e7d…"
  ```
</CodeGroup>

## Response

Returns `201 Created`. The `secret` field is present **only here**; every other endpoint returns the key without it. Persist `secret` before discarding the response.

```json 201 Created theme={null}
{
  "id": "ak_7Yq3Lm",
  "name": "production",
  "keyPrefix": "drin_a1b2c3d4e5f6",
  "last4": "1a2b",
  "senderId": null,
  "senderExternalId": null,
  "scopes": ["emails:send"],
  "lastUsedAt": null,
  "revokedAt": null,
  "createdAt": "2026-06-02T10:00:00.000Z",
  "secret": "drin_a1b2c3d4e5f6_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c"
}
```

<Warning>
  **The secret is shown once.** If you lose it, you can't recover it — there is no endpoint that re-reveals a secret. [Revoke](/api-reference/api-keys/delete) the key and create a new one.
</Warning>

<Note>
  **Foreign project.** A `senderId` that doesn't belong to your account returns `422 validation_error`.
</Note>