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:
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.
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:
{ "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 shows which roles hold what.
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. - Claude and ChatGPT: add
https://mcp.orbitwrite.com/mcpas a custom connector and sign in. See 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.