Skip to the page

API basics

API keys and scopes

Make a key, send it with each request, give it only the scopes it needs, and revoke it when a program no longer needs it or the key leaks.

Every request to the API carries a key, and the key decides two things: which account the request acts for, and what it may do there. Make one key for each program that uses DogBot, give it the fewest scopes that program needs, and you can revoke any one of them without touching the others.

Make a key

In the dashboard, open Developers → API keys and press New key.

  1. Name it after what will use it (“Website booking form”, “Make”, “Nightly sync”), up to 60 characters. The name is how you’ll tell keys apart later.
  2. Tick its scopes. A new key starts with all of them; untick what the program won’t do.
  3. Copy the key. DogBot shows it this once and keeps only a hash of it, so nobody at DogBot can show it to you again. If you lose it, revoke it and make another.

Keep the key where your program reads its secrets: an environment variable, your host’s secret settings or a secret manager. Never put it in a web page, a mobile app or a public repository, where anyone could read it.

Terminal
export DOGBOT_API_KEY="dog_live_…"

Send it with each request

Send the key as a bearer token in the Authorization header:

Terminal
curl https://getdogbot.com/api/v1/me \
  -H "Authorization: Bearer $DOGBOT_API_KEY"

The SDKs read DOGBOT_API_KEY from the environment when you don’t pass a key, and dogbot login stores one for the CLI. GET /v1/me says which account and key a request acts as, which is the quickest check that a key works:

GET/v1/meWho am I? →
curl "https://getdogbot.com/api/v1/me" \
  -H "Authorization: Bearer $DOGBOT_API_KEY"
Response200Who a key is
{
  "object": "me",
  "account": {
    "id": "acct_1Hq2LxW9cVbN3mKpRtYs0a",
    "email": "dana@example.com",
    "name": "Dana Whitfield",
    "time_zone": "America/Chicago",
    "created_at": "2026-11-01T15:00:00.000Z"
  },
  "key": {
    "id": "key_1Hq2LxW9cVbN3mKpRtYs0a",
    "name": "Website booking form",
    "prefix": "dog_live_7Hq2Lx",
    "mode": "live",
    "scopes": [
      "messages:send",
      "messages:read"
    ],
    "created_at": "2026-11-13T19:00:00.000Z"
  },
  "plan": {
    "status": "active",
    "active": true,
    "trial_end": null,
    "current_period_end": "2026-12-01T15:00:00.000Z"
  },
  "device": {
    "status": "online"
  }
}
You gotIt meansDo next
200The key works. key.scopes says what it may do.Use it.
401 unauthorized with “That isn’t a DogBot key”The key is cut short, has a typo, or isn’t a DogBot key.Copy it again, whole.
401 unauthorized with “That key isn’t valid”The key was revoked.Make a new key.
401 unauthorized with “Send your API key as Authorization: Bearer <key>”The header is missing or isn’t Bearer followed by the key.Fix the header.
403 insufficient_scopeThe key works but can’t read the account.Add account:read to the key, or skip this check.

What a key looks like

Every key is dog_live_ or dog_test_, then 32 random letters and digits, then a 6-character checksum of everything before it, 47 characters in all:

PartExample
Prefixdog_live_
32 random characterskV8yQ2nTmX4pLw7RzC9dHf3JsB6aGe1N
Checksumu0YtPq

The shape does two things:

  • A typo costs nothing. DogBot checks the shape and the checksum before it looks the key up, so a mistyped or made-up key is refused at once with 401 unauthorized.
  • A leaked key can be spotted. The fixed prefix and the checksum let secret scanners, such as GitHub’s, recognise a DogBot key that was pushed to a repository by mistake.

The dashboard and GET /v1/me name a key by its first 15 characters (dog_live_7Hq2Lx), its prefix, which is enough to tell your keys apart and too little to use.

Live and test keys

Every key the dashboard at getdogbot.com makes is a live key, dog_live_, and sends real texts from your number. dog_test_ keys belong to DogBot’s own development and preview servers: getdogbot.com refuses a test key, and those servers refuse a live one, so a key copied into the wrong place can’t act on the wrong account.

There is no test mode that pretends to send. To try something safely, send it to your own number: it arrives on your phone from your own number, and you can see every step.

Scopes

A scope lets a key use a group of operations. Give a key only the scopes its program needs, so a key that leaks can do as little as possible.

ScopeLets a keyOperations
messages:sendSend, schedule, edit, cancel and resolve texts; upload files.POST /v1/messages, PATCH /v1/messages/{id}, POST /v1/messages/{id}/cancel, POST /v1/messages/{id}/resolve, POST /v1/files, PATCH /v1/settings, POST /v1/templates, PATCH /v1/templates/{id}, DELETE /v1/templates/{id}, PATCH /v1/conversations/{id}, POST /v1/broadcasts, POST /v1/broadcasts/{id}/cancel, POST /v1/sequences, PATCH /v1/sequences/{id}, POST /v1/sequences/{id}/enrollments, POST /v1/enrollments/{id}/cancel, POST /v1/hooks, PATCH /v1/hooks/{id}, DELETE /v1/hooks/{id}, POST /v1/automations/rules, PATCH /v1/automations/rules/{id}, DELETE /v1/automations/rules/{id}, PATCH /v1/automations/away
messages:readRead texts, files, chats, lookups and the event feed.GET /v1/messages, GET /v1/messages/{id}, GET /v1/files/{id}, GET /v1/chats, GET /v1/chats/{id}, GET /v1/lookup, GET /v1/events, GET /v1/events/{id}, GET /v1/templates, GET /v1/templates/{id}, GET /v1/analytics, GET /v1/conversations, GET /v1/conversations/{id}, GET /v1/conversations/{id}/messages, GET /v1/broadcasts, POST /v1/broadcasts/preview, GET /v1/broadcasts/{id}, GET /v1/broadcasts/{id}/recipients, GET /v1/sequences, GET /v1/sequences/{id}, GET /v1/sequences/{id}/enrollments, GET /v1/enrollments/{id}, GET /v1/hooks, GET /v1/hooks/{id}, GET /v1/automations/rules, GET /v1/automations/rules/{id}, GET /v1/automations/away
contacts:writeAdd people to the stop list and take them off it.POST /v1/stops, DELETE /v1/stops/{person}, POST /v1/contacts, PATCH /v1/contacts/{id}, DELETE /v1/contacts/{id}
contacts:readRead the stop list.GET /v1/stops, GET /v1/contacts, GET /v1/contacts/{id}
webhooks:manageMake, change, test and delete webhooks; read deliveries and replay them.GET /v1/webhooks, POST /v1/webhooks, GET /v1/webhooks/{id}, PATCH /v1/webhooks/{id}, DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test, POST /v1/webhooks/{id}/rotate-secret, GET /v1/webhooks/{id}/deliveries, POST /v1/webhooks/{id}/deliveries/{delivery_id}/replay
account:readRead the Mac’s status, the account and its sending rules.GET /v1/device, GET /v1/me, GET /v1/settings

GET /v1/status, which says whether DogBot itself is up, needs no key at all.

A key without the scope an operation needs is refused with 403 insufficient_scope, and error.message names the scope. Each operation’s reference page names its scope too.

A few common choices:

What the program doesScopes
Sends texts and reads back what happenedmessages:send, messages:read
A dashboard or report that only readsmessages:read, contacts:read, account:read
Sets up its own webhooks, like a CRM integrationmessages:send, messages:read, webhooks:manage
Keeps a stop list in step with another systemcontacts:read, contacts:write

A key with every scope is a full key. A key with only messages:read, contacts:read and account:read is a read-only key, which can look at everything and change nothing.

You can’t change a key’s scopes after it’s made. Make a new key with the scopes you want, switch your program to it, then revoke the old one.

How many keys an account can have

An account can have 10 keys at once. Making an eleventh is refused with 409 limit_reached. Revoked keys don’t count, so revoke the ones you no longer use.

Revoke a key

On the Developers → API keys page, press Revoke next to the key. It stops working at once: the next request with it is 401 unauthorized. Revoking can’t be undone.

Revoking a key also deletes the webhooks a program made with that key through the API, so an integration you remove stops receiving events. Webhooks you made in the dashboard stay.

To replace a key without a gap, make the new key, put it in your program, check the program works with GET /v1/me, then revoke the old one. The Developers → API keys page shows when each key was last used, so you can see when the old one has gone quiet.

If a key leaks

Revoke it straight away, then make a new one. A leaked key with messages:send can text people from your number until it’s revoked. If you see texts in your dashboard you didn’t send, revoke every key that could have sent them, and write to support@getdogbot.com.

Keys and sign-ins

AI assistants that connect to DogBot’s MCP server, such as Claude Desktop or ChatGPT, can sign in with your DogBot account instead of a key you paste. Each gets a token that works like a key with the scopes you approved and has its own limit of 120 requests a minute. You can disconnect one at any time under Connected apps. Zapier signs in the same way. Make uses an API key. OAuth or an API key