Authentication.

Five credential families, each opening exactly one surface. This page maps them, then goes deep on the two you will mint the most: wt_ API keys with their scopes, and OAuth for third-party apps.

tokens ▸ the map

Five credentials, five surfaces.

Each credential opens exactly one slice of Writ. The fastest way to debug a 401 is to check the pair: which token, on which surface.

wt ▸ keys + scopes

API keys: one header, scoped tight.

A key is wt_ followed by 43 URL-safe characters. The secret is shown once at creation and stored hashed — lists and logs show only a short, non-secret prefix. Send it as a Bearer token:

curl https://api.usewrit.app/api/v1/workflows \
  -H "Authorization: Bearer $WRIT_API_KEY"

headers = {"Authorization": f"Bearer {os.environ['WRIT_API_KEY']}"}

const headers = { Authorization: `Bearer ${process.env.WRIT_API_KEY}` };

req.Header.Set("Authorization", "Bearer "+os.Getenv("WRIT_API_KEY"))

let req = client.get(url).bearer_auth(std::env::var("WRIT_API_KEY")?);

Scopes: resource:action

Actions are read, write, execute and delete, over seventeen resources. A key carries only the scopes you grant it — and the pinnable resources can be narrowed further, to specific ids.

Three presets cover most keys: read_only (every :read), run (:read + :execute) and full (everything, including delete). transfer is excluded from every preset and must be granted by hand. Wildcards expand to concrete scopes at grant time, so a key can never silently widen later — and enforcement is default-deny: a route not explicitly opened to API keys refuses them.

oauth ▸ third-party apps

OAuth: PKCE, no client secret.

The OAuth surface is built for public clients: PKCE is required, there is no client secret, and clients can self-register through RFC 7591 dynamic registration. Access tokens are prefixed wto_ (legacy pso_ still accepted) and work on /api/* and published /mcp/{slug} servers.

OAuth scopes are a separate, smaller set — thirteen — and a grant caps at the operator role, never admin:

account ▸ sign-in security

Locking the account itself.

Independent of API credentials, the account carries its own protections:

secrets ▸ two syntaxes

Vault refs vs AI placeholders.

Two placeholder syntaxes, two channels — do not mix them. {{vault:key}} is the workflow-field syntax: it supports subfields like {{vault:name.username}}, and a bare credentials reference resolves to the password. {{secret:key}} is the AI-channel placeholder, for when an AI session needs a secret. A workflow field wants vault:; an AI instruction wants secret:.

faq

Authentication questions, answered.

reference ▸ next

Put a token to work.