Authentication

How to present your API key, where to send requests, and what a refused request looks like.

The API key

Every request carries the key as a bearer token:

Authorization: Bearer sphk_...

The key goes in that header and nowhere else — no query parameter accepts it.

An administrator of your company issues the key in the Portal, under Settings → API keys, and can revoke it there at any time. One key acts for the whole company: there is no per-sphere scope, and no per-key permission to choose. The administrator guide covers issuing and revoking.

The value is shown once, when it is issued — Spherum stores only a hash of it. Put it wherever your integration keeps its secrets. A key that has been lost cannot be recovered: the administrator revokes it and issues a fresh one.

A missing, malformed or revoked key is refused with a 401, and a revoked key is refused exactly like one that never existed. So every call failing at once, where they worked yesterday, usually means the key was revoked rather than that any request is wrong.

Base URL

All requests go to:

https://api.spherum.ae

Paths in the reference are relative to that host and already include the /api/public/v1 prefix. So POST /api/public/v1/invitations is sent to:

https://api.spherum.ae/api/public/v1/invitations

Send the whole prefix as written — a path without /api returns 404.

Errors

A refused request answers with application/problem+json, the shape described by RFC 7807:

{
  "type": null,
  "title": "Invalid request",
  "status": 400,
  "detail": "Email is required.",
  "instance": null
}

Only title is always present. status repeats the HTTP status code, detail carries the specific reason when there is one to give, and type and instance may be null. Show title and detail to whoever has to act on the failure; branch your own code on the status code.

400 — the request could not be accepted. A body that is not valid JSON, a required field missing or malformed, or a batch over the 20-row limit. Nothing was written. A batch over the limit is refused whole, before any row is read, so no part of it is created.

401 — the key was not accepted. No Authorization header, a header that is not a bearer token, or a key that has been revoked.

404 — no such record. Only from the calls that name one: re-sending an invitation, archiving and restoring. It means nothing with that id belongs to your company.

Anything a call reports about a person is not an error. Inviting an address that already has a record answers 200 with Created: false and that record’s current status; archiving a record that is already archived answers 200 with Archived: false; a batch answers 200 with a result and, where it skipped, a reason on every row. The reference gives each response in full.