Get Past the Front Door

Three Paths, One Authenticated Request

Every call resolves to the same authorized identity. The difference is how you present it.

The most common path

OAuth 2.1 for MCP Clients

When a client first reaches the Archie MCP server, it has no token. The server answers 401 with a WWW-Authenticate header that points at the protected-resource metadata. The client reads that, discovers the authorization server, registers itself, runs a PKCE authorization, and exchanges the code for a token. Every step is standard OAuth 2.1, so a conformant client does it without you writing any auth code.

Discovery and registration endpoints

The canonical resource indicator is https://mcp.dev.arch.ie/mcp. The /mcp suffix matters, because the OAuth resource indicator is canonicalized against it. Use the full path everywhere you configure the server.

Why no client secret

Dynamic Client Registration

You never paste a client id or secret into your MCP client. Archie supports dynamic client registration (RFC 7591): on first connect the client registers itself with the authorization server and receives its own client_id on the spot. This is what makes a one-URL connector possible. There is no developer-portal step to create an OAuth app before you can connect.

• Public clients (desktop apps, editors) register without a secret and prove possession with PKCE, so there is no long-lived secret to leak.
• Registration is bound to the redirect URIs the client declares. Archie allowlists the Claude callback URIs and loopback for local clients; an unrecognized redirect URI is refused.
• Each connection gets its own registration, so revoking one client does not affect another.

What the user approves

Consent and Scopes

On the authorization step the user signs in with WorkOS (Google or Microsoft) and approves a set of scopes. The token Archie issues carries exactly those scopes, and every call is gated against them server-side. A user who cannot see a client in the web app cannot reach that client through a token either.

The scope vocabulary is the eleven-permission taxonomy the skill registry enforces: every skill declares exactly one required permission, and the bearer must carry it for the dispatch to pass. API keys pick from the same catalog, so a scope you see here is also a permission you can put on a key.

A token minted with no scope parameter carries the legacy archie:full wildcard and keeps full access, so pre-narrowing OAuth connections behave as before. Scopes are enforced by WorkOS FGA on top of the workspace-membership gate. Read-only tools never write; write tools that cross a risk threshold defer to the confirmation contract.

How long it lasts

Token Lifetime and Refresh

• An access token lives as long as the WorkOS session that backs it (default eight hours). The client refreshes transparently; you do not handle the refresh yourself.
• Revoke a connection from Dashboard → Connections. The next call from that client returns 401.
• A token that does not begin with sk_ short-circuits the API-key validation path, so JWT bearers stay on the fast path.

For backends and scripts

API Keys

Mint a key in Dashboard → Keys → Create key. Pick the permissions you need. The full sk_* value shows once, so copy it then. After that the portal stores only the prefix; you cannot retrieve the full value again.

curl https://api.dev.arch.ie/api/v1/skills/workstream.list/invoke \
  -H "Authorization: Bearer $ARCHIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 5}'

The backend validates the key against WorkOS and caches the result for five minutes per token, so the round-trip stays off the hot path. Revoking a key takes effect on the next call within that window; a rotated key keeps its parent alive for a grace period (default 24h) while you roll the new value into your secrets store.

In the browser

Portal Session

When you sign into the developers portal, WorkOS sets a session cookie. Any portal page (the playground included) calls the API with the cookie attached and the same authorization gate fires. No header needed. For programmatic or cross-origin calls, use an API key instead, since the cookie path is browser-only.

Resolution Order

Server-side, the router tries each path in order and stops at the first hit. Knowing the order helps when you are debugging why a call authenticated as a particular identity.

• Already-authenticated request state, set by middleware from the session cookie or E2E bypass.
• Bearer Archie session JWT (HS256, internal secret).
• Bearer Archie OAuth JWT (RS256, validated against the WorkOS JWKS).
• Bearer WorkOS API key (sk_*, validated via the WorkOS SDK).

When Auth Fails

Authentication failures return 401 with the canonical error envelope. Branch on code, never on message.

{
  "error": {
    "type": "authentication_error",
    "code": "auth_required",
    "message": "Authorization: Bearer <token> required. Accepts an Archie session JWT, an Archie OAuth JWT, or a WorkOS-issued API key (sk_*)."
  }
}

Common codes: auth_required, invalid_token, insufficient_scope, workspace_not_found, rate_limited. The full dictionary lives in Error handling.