Create and protect API tokens

Release availability

This guide describes the initial developer API release candidate. It requires the matching website release and database migrations before these requests work. Availability follows the database; there is no developer API environment flag. Publishing this documentation alone does not enable the API. If the token screen or API is unavailable, contact Dashio before building a production integration.

Create a token

1. Sign in to Dashio and select the Space whose domains you want to manage. You must be an owner or admin of that Space.
2. Open Developers → Access tokens in the Admin Portal.
3. Give the token a recognizable name for one integration, choose its permissions, and set an expiry. The default lifetime is 90 days; the maximum is 365 days.
4. Copy the secret immediately into your server's secret manager. The complete secret is shown once, when you create it. Dashio stores its hash and displays only a prefix afterward.

If you enrolled TOTP MFA, complete it before creating or rotating a token. Otherwise, your verified sign-in session is sufficient. Machine requests use the scoped token.

Use a separate token per integration and environment. A token is bound to exactly one Space; it cannot select another Space through a request parameter.

Choose the smallest permissions

Scopes are independent: dns:write does not include dns:read or domains:read. Select both DNS scopes if your integration reads records before changing them. Start with domains:read for the quickstart.

Tokens cannot create other tokens, manage accounts or billing, register or renew domains, initiate transfers, purchase add-ons, or configure outgoing webhooks. Those operations are outside this release.

Authenticate from your server

Send the complete opaque secret, beginning with dashio_, in the HTTP header:

Authorization: Bearer dashio_<your-secret>

Use HTTPS. Keep the secret out of browser applications, public runtime configuration, URLs, source control, screenshots, and logs. Browser session tokens and Supabase project keys are not developer API credentials. The API does not accept a signed-in browser session in place of a developer token.

For local development, use an environment variable populated through your usual secret tooling. Avoid pasting the literal token into shell commands that your terminal saves in history.

Rotate or revoke access

To replace an active token's secret, select Rotate beside it and confirm. The old secret stops authorizing new requests immediately; save the replacement once and update your integration. The token's ID, permissions and expiry stay the same. Expired and revoked tokens cannot be rotated.

For a handover without interrupting new requests, create a separate replacement token, update the integration, verify a read request, then revoke the old token. Rotation and revocation do not cancel work already in progress.

If rotation times out or its outcome is unclear, refresh the token list before another explicit attempt. The old secret may already be invalid, and Dashio cannot recover a replacement whose response was lost.

Space owners and admins can list and revoke their Space's tokens. Tokens also stop working if their creator loses the required Space role, the creator's account becomes inactive, or the Space is archived. Removing a user therefore also removes their token access; transfer ongoing integrations to another authorized owner before removing them.

If a secret may have leaked, revoke it immediately and create a replacement. A token's displayed prefix identifies it but cannot authenticate requests.

Save with a password manager

The one-time secret dialog provides labelled credential fields and optional copyable details: website, token and Space identifiers, permissions, creation date and expiry. Copy the secret separately into your password manager or server secret store.

Browser extension prompts depend on the manager and its settings. Dashio does not automatically create an API Credential item or a typed expiry field. 1Password's public website button requires a separate integration for API keys; choose the API Credential category manually when available.

Limits and request support

Each Space supports up to 20 active tokens and 10 new or rotated credentials per rolling hour. Rotating a token does not reset request quotas or extend its expiry.

The API applies shared database-backed limits of 60 requests per minute per token and 300 per minute per Space, using fixed minute windows. Creating more tokens does not increase the Space limit. Existing edge and deployment safeguards can impose additional limits. Responses after successful authentication include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. A 429 response includes Retry-After; wait at least that many seconds before trying again.

Keep the X-Request-Id response header when investigating a failed request. DNS write responses can also include X-Mutation-Request-Id, which identifies the original mutation reservation across retries and replays. Send Dashio both identifiers when available and the HTTP status, without sending your token or sensitive request data.