API keys, scopes and access

API keys belong to an institution, never to an individual subject. An institution OWNER or ADMIN signs in to the member dashboard and opens Dashboard → API keys. Those roles can create, rotate and revoke credentials. A DEVELOPER can inspect key metadata but cannot reveal secrets or change credentials; other institution roles cannot access the key inventory.

1. Sign in with an institution OWNER or ADMIN account.
2. Open Dashboard → API keys and choose Create API key.
3. Give the key a workload-specific name, such as Production reporting service. Do not name it after a person.
4. Choose test or live. Test keys begin rcn_test_; live keys begin rcn_live_.
5. Select only the scopes needed by this workload.
6. Optionally enter IPv4 or IPv6 source CIDR ranges and an expiry. Validate the observed production egress network before enforcing the restriction.
7. Create the key and copy the complete secret directly into the workload's secret manager. It cannot be retrieved later.
8. Make a low-risk verification request, confirm last-used metadata, then remove every temporary copy of the secret.

Automation can call POST /api/v1/api-keys with an institutional user's access JWT. Do not send an existing rcn_live_ or rcn_test_ key to this endpoint. The secret field appears only in the successful creation response.

curl -X POST "$RCN_API/api/v1/api-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "display_name": "Production reporting service",
    "scopes": ["credit:report", "accounts:write", "events:write"],
    "environment": "live",
    "allowed_ips": ["203.0.113.18"],
    "expires_at": "2027-02-18T00:00:00Z"
  }'

{
  "id": "key_…",
  "display_name": "Production reporting service",
  "prefix": "rcn_live_…",
  "secret": "rcn_live_…complete-one-time-secret…",
  "scopes": ["credit:report", "accounts:write", "events:write"],
  "expires_at": "2027-02-18T00:00:00Z"
}

Send the complete key as an HTTP Bearer credential. Never put it in a URL, query string, frontend bundle or NEXT_PUBLIC_ environment variable.

curl "$RCN_API/api/v1/subjects?q=Redmont" \
  -H "Authorization: Bearer $RCN_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(process.env.RCN_API_URL + "/api/v1/subjects?q=Redmont", {
  headers: {
    Authorization: "Bearer " + process.env.RCN_API_KEY,
    Accept: "application/json",
  },
});

if (!response.ok) throw new Error("RCN request failed: " + response.status);
const subjects = await response.json();

import os
import httpx

with httpx.Client(
    base_url=os.environ["RCN_API_URL"],
    headers={"Authorization": f"Bearer {os.environ['RCN_API_KEY']}"},
    timeout=10.0,
) as client:
    response = client.get("/api/v1/subjects", params={"q": "Redmont"})
    response.raise_for_status()
    subjects = response.json()

• environment accepts only test or live and determines the rcn_test_ or rcn_live_ prefix. Test and live resources are isolated server-side.
• expires_at is optional. Expired keys return 401 and cannot be restored; create a replacement.
• allowed_ips accepts IPv4 and IPv6 CIDR ranges; a single address is normalised to a host network.
• When RCN runs behind a reverse proxy, only explicitly trusted proxy ranges may supply the client-address chain.
• Institution suspension blocks every key belonging to that institution, even when the individual key remains active.
• Successful API-key authentication updates last_used_at and usage records identify the institution and API key without storing the secret.

GET /api/v1/api-keys requires api_keys.read and returns only the authenticated institution's credentials. Results contain id, display_name, prefix, scopes, active, last_used_at and expires_at. The full secret is never listed.

curl "$RCN_API/api/v1/api-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json"

1. Choose Rotate in the dashboard or POST /api/v1/api-keys/{key_id}/rotate with an OWNER or ADMIN user token.
2. Store the one-time replacement secret in the destination secret manager.
3. Deploy it to every authorised caller and perform a health check.
4. Confirm last_used_at on the replacement and investigate attempts using the old prefix.
5. Update the credential inventory, owner and next rotation date.

DELETE /api/v1/api-keys/{key_id} returns 204 and makes the credential unusable immediately. Key creation, rotation and revocation are written to the audit log.