Create an API key

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

string

required

A label to recognize the key by, shown in the dashboard.

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

string[]

Permission scopes to grant (e.g. emails:send). Omit for a key with the account’s default permissions.

Request

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"]
  }'

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…"

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.

201 Created

{
  "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"
}

The secret is shown once. If you lose it, you can’t recover it — there is no endpoint that re-reveals a secret. Revoke the key and create a new one.

Foreign project. A senderId that doesn’t belong to your account returns 422 validation_error.

Overview

Emails

Domains

Inboxes

Threads

Inbound

Webhooks

Suppressions

Contacts

Templates

Metrics

API keys

Create an API key

Body parameters

Request

Response

​Body parameters

​Request

​Response

Body parameters

Request

Response