API keys and tokens

There are two ways to authenticate against dotby, and they are for different situations.

Token	Comes from	Use it for
OAuth access token	dotby auth login, or an MCP client’s browser prompt	Your own machine, interactive work
Personal access key (dotby_pat_…)	Settings → MCP → API keys	CI, cron jobs, scripts, agent sandboxes

Both go in the same header:

curl -H "Authorization: Bearer $DOTBY_TOKEN" https://api.dotby.app/v1/me

Create a key

In the app: Settings → MCP → API keys → New key.

Give it a name that says where it runs — github-actions-release, not key 2. Six months from now that name is the only thing telling you whether it is safe to revoke.

The key is shown once. Copy it into your secret store immediately; dotby cannot show it to you again.

What a key can do

A key does exactly what its owner could do — no more.

• It is workspace-scoped. A key made in one workspace cannot touch another.
• It inherits your role. A member’s key cannot do admin things.
• It respects private projects. If you cannot see it, neither can your key.

There are no super-tokens, ever. If a script needs broader access, the right fix is the access of the account that owns it, which is visible and auditable.

The keys table

The Settings page is one table that answers the questions that matter at a glance:

Column	Tells you
Name	What it is for
Owner	Whose permissions it carries
Last used	Whether it is still alive
Expires	Which keys die this week

That last column exists because the usual failure is not a leaked key — it is a key that expired quietly at 2 a.m. and took a nightly job with it.

Headless sign-in for the CLI

The CLI can take a key without opening a browser:

printf %s "$DOTBY_PAT" | dotby auth login --with-token

Or skip login entirely and set the environment variable:

export DOTBY_TOKEN="dotby_pat_..."

Both work in CI containers and agent sandboxes with no interactive session.

Keeping keys safe

• Never commit a key. Use your CI provider’s secret store.
• One key per system. Shared keys cannot be revoked without breaking something you did not intend to break.
• Rotate on staff change. A key carries a person’s access; when the person leaves, so should the key.
• Revoke, do not just stop using. An unused key is still a live key.

If a key leaks, revoke it in the keys table. Revocation is immediate.

Rate limits

Per token: 300 reads/min and 60 writes/min.

A 429 carries Retry-After in seconds. Wait that long and retry — do not busy-retry, which just spends your next minute’s budget too.

Plan requirement

API and MCP access are Pro features. A Free workspace answers 403 with code upgrade_required. See Plans and billing.

Next

• Build your first integration — put a key to work.
• Connect an AI agent — OAuth instead of a key.
• REST API reference — every endpoint.