# auth.md — CIMS agent registration & authentication

You are an agent. This document tells you how to authenticate to the **CIMS
External API** so you can act on behalf of a CIMS user. CIMS uses standard
OAuth 2.0 — discover the metadata, obtain a bearer access token, then call the
API with `Authorization: Bearer <token>`.

- **Resource server (API):** `https://api.getcims.com/ext`
- **Authorization server (issuer):** `https://data.getcims.com/auth/v1`
- **Human sign-up / sign-in:** [https://app.getcims.com](https://app.getcims.com)

## Step 1 — Discover

Fetch the Protected Resource Metadata ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)):

```http
GET https://app.getcims.com/.well-known/oauth-protected-resource
```

It returns the `resource` identifier, the `authorization_servers` list, the
`scopes_supported`, and `bearer_methods_supported: ["header"]`. Then fetch the
Authorization Server Metadata ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414))
from the advertised issuer:

```http
GET https://data.getcims.com/auth/v1/.well-known/oauth-authorization-server
```

It carries the `issuer`, `token_endpoint`, `revocation_endpoint`,
`grant_types_supported`, and an `agent_auth` block describing registration.

If you call a protected endpoint without a token you receive
`401 Unauthorized` with a `WWW-Authenticate: Bearer resource_metadata="…"`
header pointing back at the Protected Resource Metadata above.

## Step 2 — Register

CIMS does not provision agent identities anonymously — an agent acts on behalf
of a CIMS account. Register by creating (or reusing) an account:

```http
POST https://data.getcims.com/auth/v1/signup
Content-Type: application/json

{ "email": "agent-operator@example.com", "password": "<strong-secret>" }
```

A human operator may instead create the account interactively at
[https://app.getcims.com](https://app.getcims.com). The `agent_auth.register_uri`
field in the Authorization Server Metadata always points at the current
registration endpoint.

## Step 3 — Obtain an access token

Exchange the account credentials at the token endpoint for a bearer token
scoped to the `ext` API surface:

```http
POST https://data.getcims.com/auth/v1/token?grant_type=password
Content-Type: application/json

{ "email": "agent-operator@example.com", "password": "<strong-secret>" }
```

The response is a standard OAuth token document:

```json
{
  "access_token": "<jwt>",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "<refresh>"
}
```

When the access token expires, mint a new one with the refresh token
(`grant_type=refresh_token`) rather than re-sending the password.

## Step 4 — Call the API

Present the access token as a bearer credential (the only supported
`bearer_methods_supported`):

```http
GET https://api.getcims.com/ext/<resource>
Authorization: Bearer <access_token>
```

The full operation list is in the OpenAPI document at
[https://api.getcims.com/ext/swagger.json](https://api.getcims.com/ext/swagger.json)
(human UI: [https://api.getcims.com/ext/swagger](https://api.getcims.com/ext/swagger)).

## Step 5 — Revocation

Revoke a session / token at the authorization server's revocation endpoint:

```http
POST https://data.getcims.com/auth/v1/logout
Authorization: Bearer <access_token>
```

After revocation the token is rejected — return to Step 3 to obtain a new one.

## Scopes

| Scope | Meaning                                  |
| ----- | ---------------------------------------- |
| `ext` | Access to the CIMS External API surface. |

## References

- OAuth 2.0 Protected Resource Metadata — [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)
- OAuth 2.0 Authorization Server Metadata — [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)
- The Auth.md convention — [https://github.com/workos/auth.md](https://github.com/workos/auth.md)
- Privacy — [https://www.getcims.com/legal/privacy](https://www.getcims.com/legal/privacy)
- Terms — [https://www.getcims.com/legal/terms](https://www.getcims.com/legal/terms)