Authentication | Gooclaim | API Documentation

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:

Human token

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

Machine token

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 for the rotation flow.

Step 2 — Exchange credentials for a token

$ 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:

1 {
2   "access_token": "eyJhbGciOiJSUzI1NiIs...",
3   "token_type": "Bearer",
4   "expires_in": 3600,
5   "scope": "workflow:read audit:read"
6 }

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:

$ 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:

$ 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 to query a workflow’s status.