# Authentication

> API keys for scripts and servers, OAuth sign-in for agents and the CLI, and the permissions each carries.

There are two ways to authenticate. Both send a bearer token:

```http
Authorization: Bearer <token>
```

|            | API key                                               | OAuth sign-in                                                   |
| ---------- | ----------------------------------------------------- | --------------------------------------------------------------- |
| Looks like | `orbit_sk_…`                                          | A JWT access token                                              |
| Get one    | **Settings → API keys**                               | `orbitwrite login`, or connecting Claude or ChatGPT             |
| Acts as    | The workspace                                         | You, in the workspace you picked, cut down to what you approved |
| Best for   | Scripts, servers, CI, Zapier, the OpenAI and xAI APIs | The CLI on your machine, AI apps that can sign in               |

## API keys

Owners and admins create keys under **Settings → API keys** with **Create key**. The key is shown once; copy it then.
A key belongs to the workspace, not the person who made it, and keeps working after they leave. **Revoke key** stops
it at once.

```bash
export ORBITWRITE_API_KEY=orbit_sk_...
curl https://orbitwrite.com/api/v1/me -H "Authorization: Bearer $ORBITWRITE_API_KEY"
```

`GET /me` returns the key's workspace:

```json
{ "organization": { "id": "org_123", "name": "Brightloop", "slug": "brightloop" } }
```

### Scopes

A key created in the app has the workspace's full authority. A narrower key is minted with `POST /api/v1/api-keys`
and a list of `scopes`, each a `resource:action` permission such as `post:create` or `inbox:read`. Minting needs a
signed-in owner or admin: an API key can never create another key, whatever its scopes.

A key with `post:create` but not `post:publish` can draft and schedule but not publish on its own. An unknown scope is
a `400`, so a typo can't silently leave out a permission. `GET /api-keys/permissions` lists the vocabulary, and the
[permissions reference](https://orbitwrite.com/docs/developers/reference/permissions) shows which roles hold what.

> **Warning:** A key acts as your workspace. Keep it out of source control and client-side code, and revoke any key you no longer use.

## OAuth sign-in

Clients that can open a browser sign in instead of using a key:

- **The CLI**: `orbitwrite login`. See [CLI](https://orbitwrite.com/docs/developers/cli#sign-in).
- **Claude and ChatGPT**: add `https://mcp.orbitwrite.com/mcp` as a custom connector and sign in. See [MCP](https://orbitwrite.com/docs/developers/mcp).

You pick a workspace and approve what the client may do. Its access is your role in that workspace, cut down to what
you approved, and it can never manage members, billing, API keys or the workspace itself. Disconnect a client any
time under **Settings → MCP → Connected apps**; removing you from the workspace cuts it off too.

## Who's acting

Writes made with a key are attributed to the person who created the key, so they show up in activity with a name.
Writes made through OAuth are attributed to you.