Get started

Authentication

How API keys work, where to get them, and the exact header format.

Every request to the Core API is authenticated with an API key sent in the Authorization header using the ApiKey scheme:

Header format

Authorization: ApiKey YOUR_API_KEY

There are two kinds of keys, matching the platform hierarchy (organization → tenants → assistants):

Key type	Scope	Extra header
Tenant key	One tenant and everything in it	n/a
Organization key	Any tenant in the organization	`X-Tenant-Id` (required)

Tenant keys#

The default. A tenant key authorizes requests against that tenant's resources only:

Terminal

curl https://core-api.heysadie.ai/assistants \
  -H "Authorization: ApiKey TENANT_API_KEY"

Organization keys#

An organization key can act on any tenant that belongs to the organization, but every tenant-scoped request must say which tenant via the X-Tenant-Id header:

Terminal

curl https://core-api.heysadie.ai/assistants \
  -H "Authorization: ApiKey ORG_API_KEY" \
  -H "X-Tenant-Id: 0195f1e2-1111-7000-8000-000000000000"

A few endpoints take an organization key without X-Tenant-Id, because they act on the organization rather than one tenant: the org-level audits, transcriber testing, and reads of the transcriber catalogue. Organization-level access lists them.

Where to get your keys#

Keys are managed on the API Keys page of your OnCore dashboard (view, generate, rotate). The same page also shows your client server secret, which is used to verify webhooks. It is not an API key.

Rotating a key immediately invalidates the previous one. Treat keys as secrets: keep them server-side and never ship them in browser or mobile code.

Failed authentication#

Authentication failures use the standard error envelope:

401 response

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  },
  "metadata": {
    "timestamp": "2026-07-30T12:00:00.000Z",
    "version": "1.0",
    "path": "/assistants"
  }
}

Status	Code	When
401	`UNAUTHORIZED`	Missing/malformed header, unknown key, or invalid key
400	`VALIDATION_ERROR`	Organization key used without `X-Tenant-Id`
403	`FORBIDDEN`	Tenant does not belong to this organization

For where to view, generate and rotate keys, see API Keys. If a request is being rejected, Authentication failures works through every cause.

Next steps#

Security overview: which key reaches what, and where each secret belongs.
API keys: where to view, generate and rotate them.
Errors: what a rejected request looks like.
Authentication failures: telling 401, 403 and 404 apart.

PreviousReseller quickstart NextErrors