# Nightingale auth.md

Agent registration and authentication for the Nightingale Command Center API.

## Audience

Automated agents and integrations calling `https://dashboard.nightingale-security.com/api` on behalf of a tenant user.

## Resource server

- Protected resource metadata: `https://dashboard.nightingale-security.com/.well-known/oauth-protected-resource`
- API catalog: `https://dashboard.nightingale-security.com/.well-known/api-catalog`
- OpenAPI: `https://dashboard.nightingale-security.com/openapi.json`

## Authorization server

- OAuth 2.0 metadata: `https://dashboard.nightingale-security.com/.well-known/oauth-authorization-server`
- OpenID Connect metadata: `https://dashboard.nightingale-security.com/.well-known/openid-configuration`
- Issuer: `https://dashboard.nightingale-security.com`

## Registration (verified email)

1. `POST https://dashboard.nightingale-security.com/api/auth/register` with JSON `{ "email", "password", "username", "orgName" }`.
2. Obtain a CSRF token from `GET https://dashboard.nightingale-security.com/api/csrf-token` and send it as `X-CSRF-Token` on mutations.
3. Confirm the registration email via the link sent to the verified address.
4. Sign in with `POST https://dashboard.nightingale-security.com/api/auth/login` to receive an HttpOnly `session` cookie.

### Identity assertion

- `identity_types_supported`: `verified_email`
- `credential_types_supported`: `session_cookie`, `bearer_jwt`
- `claim_uri`: https://dashboard.nightingale-security.com/auth.md#verified-email

## Session and tokens

- Browser/API session: HttpOnly `session` cookie (JWT, HS256).
- Short-lived WebSocket/VSCode token: `GET https://dashboard.nightingale-security.com/api/auth/token?scope=ws|vscode` (requires active session).
- Refresh: `POST https://dashboard.nightingale-security.com/api/auth/refresh` with CSRF protection.

## Google OAuth (optional)

When enabled, start at `GET https://dashboard.nightingale-security.com/api/auth/google` and complete at `/api/auth/google/callback`.

## Required headers

| Header | When |
|--------|------|
| `X-CSRF-Token` | All state-changing browser-originated `POST`/`PATCH`/`DELETE` |
| `Cookie: session=...` | Authenticated API calls |
| `X-Nightingale-Tenant` | Tenant-scoped worker/internal calls (validated format) |

## Scopes

See `scopes_supported` in `/.well-known/oauth-protected-resource`. Permissions are enforced per-role on each route.

## Agent skills index

`https://dashboard.nightingale-security.com/.well-known/agent-skills/index.json`

## MCP

- Server card: `https://dashboard.nightingale-security.com/.well-known/mcp/server-card.json`
- Browser tools: WebMCP registration on page load (see site layout).