---
title: "Authentication and keys"
summary: "One Bearer key acts for your whole organization. How to create, rotate and revoke it, and what a 401 means."
updated: "2026-09-30"
status: stable
origin: official
url: "https://swooshconnect.com/docs/auth/"
---

# Authentication and keys

One Bearer key acts for your whole organization. How to create, rotate and revoke it, and what a 401 means.

## For AI agents

- MUST send `Authorization: Bearer <key>` on every REST and MCP call. There is no other auth.
- MUST treat a key as full consent: it can read, post, reply and act on every account connected to the organization.
- NEVER commit a key, paste it into a prompt, or write it to a log. Use an environment variable.
- DO give each deployed agent or machine its own key, so you can revoke one without breaking the rest.
- DO stop and report on a 401. Do not retry in a loop. The key is wrong, missing or revoked.
- NEVER ask the user to paste a key into chat. Ask them to set `SWOOSHCONNECT_API_KEY` in the environment.

## What a key is

- A key is a Bearer token that starts with `sr_`. It belongs to your organization, not to a person.
- It acts on every account connected to the organization. There are no per-account or read-only keys.
- Creating a key is your consent for software that holds it to act on those accounts. Only give it to software you trust.
- An organization can hold at most 10 active keys. Revoke one to create another.

## Use a key

```bash
curl -H "Authorization: Bearer $SWOOSHCONNECT_API_KEY" https://swooshrank.com/api/v1/connect/accounts
```

## Create, rotate, revoke

- Create: portal, API keys, name the key, Create key. The full key is shown once. The list afterwards shows only a short prefix.
- Rotate: portal, API keys, Rotate on a key. It revokes the old key and makes a new one under the same name. Copy the new key at once.
- Revoke: portal, API keys, Revoke, then Confirm revoke. Anything using that key stops working immediately.
- Each row shows when the key was created and last used. Use it to find keys nobody needs.

## One key per agent

Name each key after what uses it, for example a laptop, a CI runner or one deployed agent. Every agent you deploy from the portal gets its own key. If one leaks, you revoke that one.

## When you get a 401

A missing, malformed, unknown or revoked key answers HTTP 401 with a `WWW-Authenticate: Bearer` challenge (the MCP endpoint adds realm and error details). The body uses the standard error envelope with the code unauthorized.

```json
{ "error": { "code": "unauthorized", "message": "Invalid or missing API key" } }
```

The body never echoes the key you sent. Check the header spelling, then check that the key was not revoked or rotated.

> **Never:** Never commit a key to git. If you did, rotate it in the portal now. Removing it from history is not enough.