Authenticate with the Public API

RIIW Public API requests use a service-account token or OAuth access token as an HTTP bearer credential. Send requests only from a trusted server and always use HTTPS outside local development.

Send an authenticated request

The stable base path is /api/public/v1. Include the organization ID in every organization resource URL and pass the token in the Authorization header:

curl \
  -H "Authorization: Bearer $RIIW_API_TOKEN" \
  "https://api.example.com/api/public/v1/organizations/$ORGANIZATION_ID/tasks?limit=50"

Do not send a Public API token to /api/v1; that path is reserved for interactive RIIW management sessions. Do not use a browser session token as a substitute for a Public API credential.

Use the machine-readable contract

Retrieve the OpenAPI 3.1 document from GET /api/public/v1/openapi.json. It defines supported operations, request and response DTOs, operation IDs, scopes, pagination, ETags, idempotency headers, and problem responses. Generate a client only after pinning the API version and reviewing how the generator represents cursor pagination and nullable fields.

List responses use cursor pagination. Follow the returned cursor rather than constructing one, and keep the same filters and sort context for subsequent pages. IDs are opaque strings; do not infer resource type, order, or tenant from their format.

Make safe mutations

Every POST, PUT, PATCH, and DELETE request requires an Idempotency-Key header between 8 and 255 characters. Generate one key for one logical operation and reuse it only when retrying the identical method, path, body, query, and concurrency headers.

Updates and deletes that modify versioned resources require the current ETag in If-Match. Read the resource, retain its ETag, and send it with the mutation. If another actor changes the resource first, fetch the latest representation and decide whether your change is still valid.

curl -X PATCH \
  -H "Authorization: Bearer $RIIW_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $OPERATION_ID" \
  -H "If-Match: $CURRENT_ETAG" \
  -d '{"status":"done"}' \
  "https://api.example.com/api/public/v1/organizations/$ORGANIZATION_ID/tasks/$TASK_ID"

Task statuses and transitions must belong to the project workflow. Nested sprint, tag, task, document, and file resources must belong to the project or organization named in the URL.

Protect credentials and logs

Redact Authorization, OAuth codes, refresh tokens, webhook secrets, and file download URLs. Log the HTTP status, problem code, request ID, operation ID, and affected resource ID. Keep environment-specific credentials separate and rotate them through Organization settings → API & Webhooks.

When authentication fails

A 401 generally means the token is missing, malformed, expired, rotated, or revoked. A 403 means the authenticated principal lacks a scope, capability, plan entitlement, or valid lifecycle state. A cross-organization request returns 404 even when the resource exists.

For retry and concurrency decisions, see Handle API errors, retries, and concurrency.