# auth.md

## agent_auth

```yaml
skill: https://testnimbus.dev/auth.md
register_uri: https://testnimbus.dev/portal
methods:
  - identity_type: anonymous
    credential_types: [bearer]
    claim_uri: https://testnimbus.dev/api/token
    revocation_uri: https://testnimbus.dev/api/revoke
```

You are an agent. This service supports **agentic registration**: discover → register → exchange for an access_token → call API → handle revocation. Follow the steps in order.

## Agent Registration

### Step 1 — Discover

Fetch the Authorization Server metadata to discover registration endpoints:

```http
GET /.well-known/oauth-authorization-server
```

The response includes an `agent_auth` block with registration URLs and supported identity types.

### Step 2 — Pick a method

Nimbus supports two registration methods:

1. **Local (no auth)** — The `nimbus mcp` command runs over stdio with no credentials. Agents in the terminal (Claude Code, Cursor, Copilot) invoke `nimbus test` and `nimbus mcp` directly.
2. **Remote API (OAuth 2.0)** — For remote access (e.g., `nimbus serve`), register at the portal and authenticate with a bearer token.

### Step 3 — Register

For remote API access:

1. Create an account at [https://testnimbus.dev/portal](https://testnimbus.dev/portal)
2. Navigate to **API Tokens** and generate a bearer token
3. Choose your credential type: `client_secret` (server-side agents) or `private_key_jwt` (CI/CD agents)

### Step 4 — Authenticate

Present the bearer token as an Authorization header:

```http
GET /api/resource
Authorization: Bearer <access_token>
```

### Scopes

| Scope | Description |
|---|---|
| `api:read` | Read test results, coverage, configuration |
| `api:write` | Execute tests, modify configuration |
| `offline_access` | Long-lived refresh tokens for background agents |

### Revocation

To revoke an access token, POST the token to:

```http
POST /api/revoke
Content-Type: application/x-www-form-urlencoded

token=<access_token>
```

### Endpoints

| Resource | URL |
|---|---|
| Registration portal | `https://testnimbus.dev/portal` |
| Token endpoint | `https://testnimbus.dev/api/token` |
| Revocation | `https://testnimbus.dev/api/revoke` |
| JWKS | `https://testnimbus.dev/.well-known/jwks.json` |