# auth.md

> How an automated client obtains credentials for Openpulse at https://openpulse.cloud.

Generated at build time. The machine-readable version of everything here is
[`/.well-known/oauth-protected-resource`](https://openpulse.cloud/.well-known/oauth-protected-resource);
this file is the same thing in prose, for a client that reaches it first.

## Who this is for

Agents acting **on behalf of a person who already has an Openpulse workspace**. There
is no self-serve credential for an agent acting on its own behalf, and that is a
product decision rather than an omission: every tool here reads one workspace's
private data, so there is nothing an unattached agent could be authorised to see.

## Registration

The MCP server at `/mcp` is an OAuth 2.1 **resource server**. It verifies tokens and
issues none. Clerk is the authorization server: it runs the consent screen, supports
dynamic client registration (RFC 7591), and mints the tokens this API accepts.

1. `POST` or `GET` any MCP method without a token. The reply is `401` with
   `WWW-Authenticate: Bearer resource_metadata="…"`.
2. Fetch that document. Its `authorization_servers` array names the issuer.
3. Fetch the issuer's `/.well-known/oauth-authorization-server`, register at its
   `registration_endpoint`, and run the authorization code flow with PKCE.
4. Send the access token as `Authorization: Bearer …` to `/mcp`.

The registration endpoint is advertised by the authorization server rather than fixed
here, because it is Clerk's to move: read it from
[`/.well-known/oauth-authorization-server`](https://openpulse.cloud/.well-known/oauth-authorization-server),
where the `agent_auth` block repeats it alongside the identity and credential types
this resource accepts.

## Credential types

| Type | Used for | Obtained from |
| --- | --- | --- |
| OAuth 2.1 access token | `/mcp` | Clerk, via the flow above |
| API key (`op_live_…`) | `/v1` | A workspace admin, in workspace settings |

A **session cookie is never accepted** on either surface. The two carry different
audiences and only one of them was minted for this resource; a browser session
presented to `/mcp` is rejected rather than honoured.

## Revocation

An OAuth client's access is revoked by the person who granted it, from their Clerk
account's connected-applications list. An API key is revoked by a workspace admin in
workspace settings; revocation is immediate. Report a leaked credential to
[support@openpulse.cloud](mailto:support@openpulse.cloud) and see
[`/.well-known/security.txt`](https://openpulse.cloud/.well-known/security.txt).

## Scopes

The API-key scope vocabulary is listed in [`/api.md`](https://openpulse.cloud/api.md) and published
in `scopes_supported` on the protected-resource metadata. A key always acts as a
member, never an admin.