API Tokens

Org-scoped tokens

An org-scoped token is bound to a single organization and can never read or write another. Organization Administrators mint them from the API tokens screen. These are the right choice for integrations acting on behalf of one tenant: pushing use cases from an internal portal, pulling risk data into a data warehouse, or driving a reporting job.

• Prefixed rai_ so they are recognizable in logs and secret scanners.
• Scoped at mint time to the specific read and write capabilities the integration needs.
• Subject to per-organization rate limits.
• Optional expiry date; unexpiring tokens are permitted but discouraged.

Platform tokens

A platform token is not tied to one organization. It is minted only by Super Admins and is intended for platform-level automation such as the AI Catalog Curator pipeline, which writes shared reference data rather than tenant data. Platform tokens bypass per-organization rate limits by design, so they are held to tighter issuance and review expectations.

Scopes

• Pick the narrowest scope set that makes the integration work; scopes can be reduced later by reminting.
• Read scopes cover registers, reports, and coverage data.
• Write scopes cover intake submission, register updates, and catalog contribution where permitted.
• A token can never exceed what the minting role itself is allowed to do.

The secret is shown once

When you mint a token, the full secret is displayed exactly once. RAIC stores only a hash of it, so the value cannot be recovered later — not by you, not by support, not by an administrator. Copy it into your secret manager immediately. If it is lost, revoke the token and mint a replacement.

Rotation and revocation

• Rotate on a schedule and after any suspected exposure or staff change.
• Mint the replacement first, cut the integration over, then revoke the old token — this avoids downtime.
• Revocation takes effect immediately; in-flight requests using the token fail on their next call.
• Revoked tokens remain listed with their revocation reason so the history stays intelligible.

Using a token

Send the token as a bearer credential on the Authorization header of each request. Do not put it in a query string, where it will land in access logs and browser history. Never embed a token in client-side code — anything shipped to a browser is public. The full endpoint surface, error envelope, and rate-limit headers are documented on the REST API Reference page.

Audit coverage

Minting, scope changes, rotation, and revocation each write an org-scoped audit entry mirrored to the platform audit log. Authentication rejections are logged with the presented token hashed rather than stored, and repeated failures are throttled, so a misconfigured client shows up clearly without flooding the log or leaking the credential.