OAuth or an API key
An assistant connects to BlueBot's MCP server by signing in with OAuth or by sending an API key. How each works, which scopes to give it, and how to cut it off.
BlueBot's MCP server takes two kinds of sign-in, and both reach the same tools with the same rules.
| OAuth sign-in | API key | |
|---|---|---|
| Setup | Paste the server address; the client opens a BlueBot page where you sign in and approve it. | Make a key, then put it in the client's config as a header. |
| Suits | Claude Desktop, claude.ai, ChatGPT, VS Code: clients with a sign-in button. | Claude Code, Cursor, Windsurf, scripts, and any client without OAuth. |
| What it can do | The scopes on the approval page. | The scopes you tick on the key. |
| Lasts | Until you disconnect it. The client renews its access by itself. | Until you revoke the key. |
| Cut it off | Developers → Connected apps → Disconnect | Developers → API keys → Revoke |
OAuth sign-in
OAuth lets an assistant connect with nothing to copy and paste, and no key sitting in a config file.
Add the server
In your client, add a custom connector or MCP server with the address https://usebluebot.com/mcp. has the steps for each client.
Approve it
The client opens BlueBot in your browser. Sign in if you aren't already, and read the approval page: it names the app asking, the BlueBot account it would reach, and what it could do. Press Allow.
Use it
The client comes back connected and lists BlueBot's tools. Ask it "Is my Mac online?" to check.
Underneath, the client registers itself with BlueBot, sends you to BlueBot to approve it with the authorization code flow and PKCE, and gets back an access token that lasts an hour and a refresh token it uses to get the next one. Each refresh token works once. If one is ever used twice, which happens when a token is stolen and both copies are used, BlueBot ends the connection and the client asks you to sign in again.
A token works where the client asked for it to work. Clients name that with the resource parameter (RFC 8707): a token asked for https://usebluebot.com/mcp works only on the MCP server, one asked for https://usebluebot.com/api/v1 works only on the REST API, and one asked for https://usebluebot.com, or for no resource at all, works on both, as an API key does.
An OAuth connection asks for the scopes its tools use: messages:send, messages:read, contacts:read, contacts:write and account:read. It never gets webhooks:manage. When you want an assistant that can only read, connect it with a read-only API key instead.
An API key
Make a key for the assistant
In Developers → API keys, press New key. Name it after the assistant ("Claude Code on my laptop"), so you know which to revoke later, and tick its scopes:
| You want the assistant to | Tick |
|---|---|
| Read your texts and contacts and check your Mac | messages:read, contacts:read, account:read |
| Do that, and send and schedule texts | Those three, and messages:send |
| Use every tool, saving contacts too | Those four, and contacts:write |
Copy the key. It's shown once.
Keep it out of the config file
Put the key in your environment and have the config refer to it, as the examples in do:
export BLUEBOT_API_KEY="bb_live_…"Cursor and Windsurf read ${env:BLUEBOT_API_KEY} in their config files, and Claude Code reads $BLUEBOT_API_KEY when you add the server. A config file with a key pasted in is a secret: never commit .cursor/mcp.json or .vscode/mcp.json with a key in it.
Send it as a header
Every request carries the key as Authorization: Bearer bb_live_…. The client does this once it's configured.
Give each assistant its own key. Then you can revoke one without touching the others, and the request log in Developers shows which assistant did what. An account can have 10 keys.
Cut an assistant off
- An OAuth connection: open Developers → Connected apps and press Disconnect beside it. Its tokens stop working at once, and its next tool call fails until you sign it in again.
- An API key: open Developers → API keys and press Revoke. The key stops working on its next request. Revoking also deletes any webhooks a program made with that key.
Removing the server from your client's settings doesn't revoke anything at BlueBot. If you're done with an assistant, or a laptop with a key on it is lost, revoke it in the dashboard as well.
| You got | It means | Do next |
|---|---|---|
| The client asks you to sign in to BlueBot again | Its connection was disconnected, or its refresh token was refused. | Sign in again. If you didn't disconnect it, look at Developers → Connected apps for anything you don't recognize. |
Every tool call fails with unauthorized | The key was revoked or mistyped. | Make a new key and put it in the client's config. |
Send tools fail with insufficient_scope | The key is read-only. | Working as meant. For sending, use a key with messages:send. |