# Auth

The Auth API returns the identity Firetiger attached to the current request. It
is primarily useful for SDK, integration, and local workload-auth smoke tests.

**Service**: `firetiger.auth.v1.AuthService`

**Access**: Authenticated

## Methods

| Method | Description |
|:-------|:------------|
| [GetAuth](#getauth) | Return the current request identity and sanitized auth evidence |
| [MintAgentSessionToken](#mintagentsessiontoken) | Mint a short-lived agent session token from a workload proof |

---

## GetAuth

Return the actor, effective subject, organization, optional session, and
sanitized evidence for the current request.

```
GET /v1/auth
```

**Example**

```bash
curl "{{ site.api_url }}/v1/auth" \
  -u "$USERNAME:$PASSWORD"
```

**Response**

```json
{
  "identity": {
    "actor": "users/user_123",
    "subject": "users/user_123",
    "organization": "org_123",
    "session": ""
  },
  "evidence": {
    "authenticator": "basic",
    "provider": "",
    "externalIdentity": ""
  }
}
```

**Response fields**

| Field | Type | Description |
|:------|:-----|:------------|
| `identity.actor` | string | Authenticated credential source, such as `users/{id}` or `service-accounts/{id}` |
| `identity.subject` | string | Effective Firetiger entity the request acts as, such as `users/{id}` or `agents/{id}` |
| `identity.organization` | string | Organization ID used to scope the request |
| `identity.session` | string | Optional agent session resource attached to the request |
| `evidence.authenticator` | string | Authenticator that accepted the request |
| `evidence.provider` | string | Workload provider, when applicable |
| `evidence.externalIdentity` | string | Sanitized external identity, when applicable |

---

## MintAgentSessionToken

Mint a short-lived, signed **agent session token** for an agent session. An agent
authenticates this call with its raw workload proof
(`Authorization: Firetiger-Workload <proof>`), which proves only the service
identity — it carries no organization. The server **derives the organization
authoritatively from the named session** (the agent never asserts its own org)
and returns a signed token the agent then presents as
`Authorization: Firetiger-Session <token>` on every other request. This endpoint
is the only place a raw workload proof is accepted; all data routes require the
minted session token.

```
POST /v1/auth/session-token
```

**Example**

```bash
curl "{{ site.api_url }}/v1/auth/session-token" \
  -H "Authorization: Firetiger-Workload $PROOF" \
  -H "Content-Type: application/json" \
  -d '{"session": "agents/change-monitor/sessions/01J..."}'
```

**Request fields**

| Field | Type | Description |
|:------|:-----|:------------|
| `session` | string | Agent session resource (`agents/{agent}/sessions/{id}`) to mint a token for. The caller's effective subject and organization are derived from this session. |

**Response**

```json
{
  "token": "<ES256 (ECDSA P-256) signed JWT>",
  "expiresAt": "2026-05-30T12:30:00Z"
}
```

**Response fields**

| Field | Type | Description |
|:------|:-----|:------------|
| `token` | string | The minted `Firetiger-Session` token to present on subsequent requests |
| `expiresAt` | string (RFC 3339) | When the token expires; refresh before it lapses |