Authentication

Access to the ORION Data API uses per-integration credential pairs issued by the customer’s ORION environment:

1. Client ID — identifies the customer organization and your integration. Passed in the URL path.
2. API key — the secret paired with your Client ID. Passed in the x-api-key header.

Each credential pair is scoped to a single customer. Overspace operates the validation infrastructure but never holds your raw API key — only the customer’s environment can issue or revoke it.

Making an authenticated request

curl https://api.overspace.io/orion/v1/customers/osc_x7k2q9_9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d/score \
  -H "x-api-key: your-api-key"

Credential	Where it goes	Description
Client ID	URL path (/customers/{clientId}/...)	Identifies which customer’s score you’re retrieving
API key	x-api-key header	Secret that authenticates your Client ID

Client ID format

Client IDs begin with osc_ and should be treated as opaque identifiers — pass them exactly as issued:

osc_x7k2q9_9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d

Requests with a malformed Client ID are rejected with 400 INVALID_CLIENT_ID before any credential lookup occurs.

Getting your credentials

Credentials are created by the organization sharing its data, directly in their ORION environment. When an organization authorizes you, an administrator:

1. Opens the Share page in ORION and creates a New Authorization
2. Selects your organization type — insurance provider, auditor, regulatory body, or partner — and the data scopes to share: QR Score, Score Trend, and/or Pillar Breakdown
3. Optionally sets an expiration date for the authorization

ORION then generates your Client ID and API key. The API key is displayed exactly once, at creation — the organization delivers it to you through their preferred secure channel, and Overspace never holds the raw key. You’ll receive one credential pair per organization that has authorized you, and your access is limited to the scopes they selected.

Contact your Overspace representative or email support@overspacehq.com with questions about access.

Revocation and expiry

The organization can revoke an authorization at any time from the same Share page, and authorizations with an expiration date stop working automatically. Requests made with a revoked or expired credential return 401 CREDENTIAL_INACTIVE.

Error responses

Status	Code	Description
400	MISSING_CLIENT_ID	No Client ID provided in the path
400	INVALID_CLIENT_ID	Client ID does not match the expected format
401	MISSING_API_KEY	No x-api-key header provided
401	INVALID_API_KEY	API key validation failed
401	CREDENTIAL_INACTIVE	The credential has been revoked or is not active
403	—	Request blocked by edge security policy
404	CREDENTIAL_NOT_FOUND	No credential exists for this Client ID
429	—	Rate limit exceeded — retry after the Retry-After header value

Example error response

{
  "error": "Unauthorized",
  "code": "INVALID_API_KEY",
  "message": "API key validation failed",
  "timestamp": "2026-03-18T20:00:00.000Z"
}

Rate limits

Requests are rate-limited per credential. If you exceed the limit, you’ll receive a 429 response with a Retry-After header indicating how many seconds to wait before retrying.