# Atisbo auth.md

How an agent obtains, uses and loses a credential for the Atisbo MCP API.
Canonical URL: https://www.atisbo.dev/auth.md · Last updated: 2026-08-23

You are an agent. This document tells you how to obtain, use and lose a credential for the
Atisbo API. Read it top to bottom; it follows the structure of the
[auth.md draft](https://workos.com/auth-md) so you can walk it step by step.

One thing to know before you start: **Atisbo does not implement agentic registration.** There is
no OAuth authorization server, no `agent_auth` block, no identity assertion (`id-jag`)
exchange, and no claim ceremony. The only credential
that exists is an **MCP API key**, created by a human in the product's settings. Your job in this
flow is narrow: make sure your user has a key, then use it correctly.

## Step 1 — Discover

The handshake answers without a key: `initialize`, `ping`, the notifications and
`tools/list` all respond unauthenticated, so you can identify the server and read its full
tool surface before your user creates anything. The gate is at the work: an unauthenticated
`tools/call` answers with a JSON-RPC error plus a standard `WWW-Authenticate` challenge
naming the Protected Resource Metadata:

```
POST https://app.atisbo.dev/api/mcp
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "atisbo_orient" } }

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://app.atisbo.dev/.well-known/oauth-protected-resource"
{ "jsonrpc": "2.0", "error": { "code": -32000, "message": "Invalid or missing API key" }, "id": 1 }
```

Fetch that metadata URL to learn the resource identifier, the supported bearer method and the
scopes a key can carry. What exists for discovery:

- Protected Resource Metadata (https://app.atisbo.dev/.well-known/oauth-protected-resource): RFC 9728 —
  the resource identifier, `bearer_methods_supported: ["header"]`, and the real scopes. It
  deliberately declares no `authorization_servers`, because Atisbo runs no OAuth issuer.
- The OpenAPI specification (https://app.atisbo.dev/api/openapi.json) declares the security scheme:
  `type: http`, `scheme: bearer`, with the two real scopes under `x-scopes`, plus the
  versioning, pagination, sandbox and batching policies.
- The MCP manifest (https://www.atisbo.dev/.well-known/mcp.json) names the endpoint, its transport
  (`streamable-http`) and its auth type.
- This document, linked from [the developer hub](https://www.atisbo.dev/developers).

## Step 2 — Pick a method

There is exactly one method, so this section is short on purpose:

1. **Your user has an MCP API key** → use it (Steps 3 and 5). This is the only supported path.
2. **Your user does not have one** → they create it themselves (Step 4). You cannot create,
   mint or self-register a credential, and there is no registration endpoint to call.

A second scope named `provisioning` exists in the key schema. It is operator-only and is never
issued through any public flow — do not spend time looking for a way to request it. Everything an
agent can legitimately do runs on a `workspace`-scoped key.

## Step 3 — Register

Registration is the human creating the key. Nothing here is automated, and asking your user to do
it takes under a minute:

1. Create an account (or sign in) at https://app.atisbo.dev/login — the free plan needs no card.
2. Open **Settings → Account → Connect agents**.
3. Create an MCP API key and give it a label. The plaintext is shown once, then never again —
   your user should paste it straight into your configuration.

Keys carry the prefix `senso_mcp_` followed by 32 hexadecimal characters, and each one is bound
to the single workspace it was created from.

## Step 4 — Claim

Nothing to do. There is no out-of-band claim ceremony: the key belongs to whoever generated it in
Settings, works immediately, and was never pending confirmation. If your user is holding a key,
it is live.

## Step 5 — Use the credential

Send the key as a bearer header to the JSON-RPC 2.0 endpoint over HTTP POST:

```
POST https://app.atisbo.dev/api/mcp
Authorization: Bearer senso_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {} }
```

After `initialize`, call `tools/list` to discover the tool surface. Any MCP client that accepts
a Streamable HTTP URL plus custom headers works as-is: give it
`https://app.atisbo.dev/api/mcp` as the URL and `Authorization: Bearer <key>` as a header, and skip
OAuth configuration entirely — none exists.

The key sees one workspace: the same evidence, problems and decisions a signed-in member of that
workspace sees, gated the same way. It grants nothing outside it.

## Errors

Authentication errors come back as JSON-RPC error objects, not HTML:

| HTTP | JSON-RPC code | Meaning |
|---|---|---|
| 401 | -32000 | `Invalid or missing API key` — the header is absent, malformed, or the key was revoked. Do not retry unchanged; get a valid key (Step 3). |
| 429 | -32002 | `Rate limit exceeded. Retry after <N>s.` — wait the stated interval, then retry. |
| 200 | varies | Protocol-level failures (unknown method, bad params) use normal HTTP 200 with a JSON-RPC error object, per the JSON-RPC spec. |

## Revocation

Revocation is deletion in the same place the key was made: **Settings → Account → Connect
agents → delete**. There is no programmatic revocation endpoint.

Two timing facts worth knowing: a deleted key stops working within about five minutes on servers
that still hold a warm auth cache, and immediately elsewhere. Generating a replacement key takes
effect instantly, so the fast path around a compromised key is delete-plus-recreate, not waiting
out the cache.

## Reference

- [OpenAPI specification](https://app.atisbo.dev/api/openapi.json) — every public operation and the security scheme
- [Developer hub](https://www.atisbo.dev/developers) — all surfaces listed in one page
- [Documentation](https://app.atisbo.dev/docs) — the product model behind the tools
- [auth.md draft](https://workos.com/auth-md) — the format this document follows