Every request to /api/v2 is authenticated with an API key sent as a bearer token:
Requests without a valid key return 401.

​
Connect a client

For the MCP server, the SDKs, and the CLI you never handle a key yourself:
A browser opens where you are already signed in, you press Approve, and the client receives a scoped key that expires in 90 days. This works with every sign-in method, including Google and magic link, because approval happens in the browser. The credential is stored at ~/.diagrams-so/credentials.json, readable only by you, and is shared by the MCP server and both SDKs on that machine. Connected apps appear under Settings → AI Provider with a Device badge, and you can revoke any of them in one click.
Re-connecting from the same machine replaces that machine’s previous key instead of adding another one, so keys do not pile up.

​
Create a key manually

For CI, servers, or raw HTTP, create a key under Settings → AI Provider → Create key and send it as a bearer token.

​
Keys

  • Shown once. The full key is returned only at creation. If you lose it, revoke it and create a new one.
  • Live vs test. dgz_live_ keys run against production. dgz_test_ keys run in test mode (see below).
  • Expiry. Set an expiry of 30 days, 90 days, or never. Keys created by login expire in 90 days.
  • Revoke anytime. Revocation takes effect immediately.
Keys are stored only as a salted, peppered hash. The raw key is never persisted and cannot be recovered by anyone, including staff. See Security.

​
Scopes

Each key carries scopes so you can grant least privilege: In the app these appear as a simple Read-only, Write-only, or Read & write choice per resource.

​
Test mode

A dgz_test_ key runs in test mode, which exercises the full API and applies lower rate limits so you can develop against realistic behavior.
Test mode is not free. dgz_test_ keys bill the same credits as a live key, drawing your real balance. Use them to validate your integration, not to avoid spend. Check your balance with the usage endpoint.

​
Handling failures

401 Unauthorized

Missing, malformed, expired, or revoked key.

403 Forbidden

Key lacks the scope for this action.

429 Too Many Requests

Slow down and retry.

402 Out of credits

Top up to run billable actions.