Skip to content

authentication.mdx

Latest commit

 

History

History
105 lines (77 loc) · 3.1 KB

authentication.mdx

File metadata and controls

105 lines (77 loc) · 3.1 KB
Raw
title Authentication
description How to obtain, send, and rotate JWT credentials for the ResQ Infrastructure and Coordination APIs.

import CallEvidence from "/snippets/api/call-evidence.mdx"; import AgentAuthGuidance from "/snippets/api/agent-auth-guidance.mdx"; import EnvCredentials from "/snippets/api/env-credentials.mdx"; import TokenRefresh from "/snippets/api/token-refresh.mdx";

The ResQ Infrastructure API authenticates requests with a bearer JWT. You exchange a username and password for a token at POST /login, then send the token as an Authorization: Bearer <token> header on every protected request.

Operator credentials are issued out-of-band by your ResQ administrator. There is no public sign-up flow — every operator is tied to an organization and a set of mission scopes.

The flow

`POST /login` with a JSON body like `{"username": "...", "password": "..."}`. 
```bash
curl -X POST https://api.resq.software/login \
  -H "Content-Type: application/json" \
  -d '{"username":"OPERATOR","password":"REDACTED"}'
```
On success the API returns a JWT and a Unix-second expiry timestamp. 
```json
{
  "token": "eyJhbGciOi...",
  "expires_at": 1746345600
}
```

On failure you get a `401` with an `AuthError` body.

```json
{ "error": "Invalid credentials" }
```
Attach the token to every request that targets a protected endpoint. 
<CallEvidence />

Token lifetime

expires_at is a Unix timestamp in seconds. Treat it as authoritative — do not parse the JWT body to derive expiry.

A robust client should:

  1. Cache the token in memory only (never on disk in plaintext).
  2. Refresh proactively when fewer than 60 seconds remain.
  3. Re-authenticate from credentials on 401 Unauthorized.

Storing credentials safely

Never commit credentials to source control or pass them on the command line. Use environment variables or your platform's secret manager.

Rotation

Rotate operator credentials at least quarterly, and immediately if a token may have been exposed. Revocation is handled server-side; clients only need to re-run the login flow.

Coordination API

The Coordination API accepts the same JWT for protected admin and mission-approval routes (for example, POST /admin/missions/approve). Public ingestion endpoints — telemetry batches, IPFS uploads — may use a separate service token issued through your administrator. Confirm the exact scheme for your deployment.

Errors you should handle

Status Meaning What to do
401 Token missing, expired, or invalid Re-authenticate, then retry once
403 Token valid but lacks the required scope Surface to the operator; do not retry
429 Too many requests Back off and retry with jitter

See Errors for the full envelope and status-code reference.