> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.docs.gooclaim.com/llms.txt.
> For full documentation content, see https://api.docs.gooclaim.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.docs.gooclaim.com/_mcp/server.

# Authentication

Every Gooclaim API call requires a **JWT (JSON Web Token)** in the
`Authorization` header. Tokens are issued by the **Auth Service** and signed
with RS256.

## Two token types

Gooclaim issues two kinds of tokens depending on **who** is calling:

Issued to a real user (TPA admin, claim handler) after login.
Short-lived (15 min). Refreshable.

Issued to your backend service for server-to-server calls (e.g. CMS pull,
webhook delivery). Short-lived (1 hour). Auto-rotated by your client SDK.

You'll almost always use **machine tokens** for backend integrations. Human
tokens are for the Portal and Copilot web apps.

## Step 1 — Get your credentials

When your tenant is onboarded, you receive:

| Credential      | Where it goes                                        |
| --------------- | ---------------------------------------------------- |
| `client_id`     | Body of `/v1/auth/token`                             |
| `client_secret` | Body of `/v1/auth/token` (**never** in URLs or logs) |
| `tenant_id`     | All subsequent API calls carry this in the JWT       |

Rotate `client_secret` immediately if leaked — see
[Support](/home/resources/support) for the rotation flow.

## Step 2 — Exchange credentials for a token

```bash
curl -X POST https://api.gooclaim.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'
```

Response:

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "workflow:read audit:read"
}
```

Tokens expire in **1 hour** for machine tokens, **15 minutes** for human
tokens. Cache the token and re-request **before** expiry — do not retry on
401 in a loop.

## Step 3 — Call any Gooclaim API

Send the token in the `Authorization` header:

```bash
curl https://api.gooclaim.com/v1/workflows/wf_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
```

## Token verification (introspection)

To verify a token without parsing it yourself, call the introspect endpoint:

```bash
curl -X POST https://api.gooclaim.com/v1/auth/introspect \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -d '{"token": "eyJhbGciOiJSUzI1NiIs..."}'
```

Response includes the token's `tenant_id`, `scope`, `exp`, and `active` status.

## JWT claims you'll receive

| Claim       | Type   | Meaning                                                       |
| ----------- | ------ | ------------------------------------------------------------- |
| `sub`       | string | Subject — `client_id` (machine) or `user_id` (human)          |
| `tenant_id` | string | Your tenant identifier — enforced on every call               |
| `scope`     | string | Space-separated permissions (e.g. `workflow:read audit:read`) |
| `iat`       | int    | Issued-at (UNIX time)                                         |
| `exp`       | int    | Expiry (UNIX time)                                            |
| `aud`       | string | Audience — always `gooclaim-api`                              |

## Security rules

* **Never** put `client_secret` in client-side code (browsers, mobile apps).
* **Never** log full tokens. Log token IDs or a hash prefix only.
* **Always** verify the `aud` and `iss` claims if you parse tokens yourself.
* Rotate `client_secret` every 90 days.

## Rate limits

| Endpoint                   | Limit                                   |
| -------------------------- | --------------------------------------- |
| `POST /v1/auth/token`      | 60 requests per minute per `client_id`  |
| `POST /v1/auth/introspect` | 600 requests per minute per `client_id` |

Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header.

## Next: call your first API

With a valid token, head to [Workflows](/home/get-started/workflows) to query
a workflow's status.