Authentication — Drin Docs

Send the key in the Authorization header:

Authorization

Authorization: Bearer $DRIN_API_KEY

Create and revoke keys in the dashboard under API Keys, or over the API (POST /v1/api-keys). The secret is shown once at creation — store it immediately; you can't read it back.

Keep keys server-sideAPI keys are secrets. Use them only from server-side code, never in a browser, mobile app, or anything shipped to a user. If a key leaks, revoke it and mint a new one.

01 Choosing the sending project

A Drin account can hold several projects, each with its own sender identity, domains, and keys. Two kinds of key decide how the project is chosen.

Project-scoped keyTied to one project. The project is implied — send with just the Authorization header, nothing else.

Account-wide keySpans every project. You must name the project per request so Drin knows who's sending.

Name the project on an account-wide key with the X-Drin-Product header:

Headers

Authorization: Bearer $DRIN_API_KEY
X-Drin-Product: my-project        # the project's external id

Header aliasesX-Drin-Product is the canonical header. X-Drin-Sender is an accepted alias — it's what the SDK's sender option, the CLI's --sender flag, and the DRIN_SENDER env var send. All three name the same thing.

In the SDK, pass sender once when you construct the client:

Node.js

const drin = new DrinClient({
  apiKey: process.env.DRIN_API_KEY,
  sender: "my-project", // only needed for account-wide keys
});

02 Request headers

Header	Required	Purpose
`Authorization`	Always	`Bearer <api-key>`.
`Content-Type`	On `POST` / `PATCH`	`application/json`.
`X-Drin-Product`	Account-wide keys	Names the sending project (alias: `X-Drin-Sender`).
`Idempotency-Key`	Optional	Safe-retry a `POST` (see below).

03 Idempotency

Pass an Idempotency-Key on any POST to make it safe to retry — if the same key arrives twice, Drin returns the original result instead of sending again. Keys are honored for 24 hours, per sending project.

curl https://api.drin.run/v1/emails \
  -H "Authorization: Bearer $DRIN_API_KEY" \
  -H "Idempotency-Key: order-1234-receipt" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "email": "hi@acme.com" },
    "to": [{ "email": "a@b.com" }],
    "subject": "Receipt",
    "html": "<p>Thanks!</p>"
  }'

The SDK automatically retries transient failures (429 and 5xx) with exponential backoff — and it only retries a POST when you've supplied an Idempotency-Key, so a send is never duplicated. See Errors for the full retry behaviour.