Skip to main content
Every request except GET /v1/health needs an API key, sent as a bearer token:
A missing, malformed, revoked or expired key gets 401 invalid_key.

​
Keys

  • One firm per key. A key always acts for the firm it was issued to; there is no header to choose a firm. Another firm’s claims return 404 not_found.
  • One purpose per key. Each key is issued for one integration or system. A new purpose means a new key.
  • Shown once. OSA stores only a fingerprint of the key. Keys are delivered through a one-time, expiring link and are never sent by plain email. If a key is lost, ask OSA for a new one.
  • Rotation. Ask OSA for a replacement key; both keys work while you switch over, then the old one is revoked.
  • Revocation takes effect within about a minute.
  • Expiry. A key does not expire unless an expiry date was agreed when it was issued.
Keys belong on your servers only. Never embed one in a browser page, a mobile app, logs, or source control. If a key may have leaked, contact OSA to revoke it.

​
Permissions

Each operation needs a permission (scope). Your key has the permissions that your firm’s plan includes and that the key was issued for. Your firm’s plan can change without a new key; what a key was issued for is fixed, so a wider purpose means a new key. GET /v1/me shows what your key has now, as scopes. A valid key without the needed permission gets 403: insufficient_scope when the key’s purpose doesn’t include it, or not_in_plan when your firm’s plan doesn’t.