# 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`. [Connect your assistant](https://usebluebot.com/docs/mcp#connect-your-assistant) 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 [Connect your assistant](https://usebluebot.com/docs/mcp#connect-your-assistant) do: ```bash 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`. | ## Next - [MCP tools](https://usebluebot.com/docs/mcp/tools): Which scope each tool needs. - [API keys and scopes](https://usebluebot.com/docs/concepts/api-keys): Every scope, and keys for the REST API.