Authentication
One key in one header. The key decides the environment, and every request goes to app.pacspace.io.
Every request to the records API carries your workspace's API key in the x-api-key header. There is one host, https://app.pacspace.io, for Sandbox and Production alike; the key decides which one your request reaches.
Keys
Make a key in the dashboard under Settings, Developer, API keys, with Sandbox or Production in view. A key belongs to the environment it was made in, and it reads and writes only there.
pk_{environment}_{publicId}.{secret}| Prefix | Environment | What it reaches |
|---|---|---|
pk_test_ | Sandbox | Your Sandbox records. Nothing here touches Production. |
pk_live_ | Production | Your Production records. |
The key is shown once. Store the whole string as one value; never split it, log it, or put it in a browser. The SDKs read the environment from the key, so new PacSpace({ apiKey }) and PacSpace(api_key=...) need nothing else.
Making a request
Reading the history of an evaluation run's record, eval-run-4417:
import { PacSpace } from '@pacspace-io/sdk';
const pac = new PacSpace({ apiKey: process.env.PACSPACE_API_KEY! });
const history = await pac.records.history({ record: 'eval-run-4417' });Rotating a key
Make a new key, move your systems to it, then disable the old one from the same page. Or rotate the key in place: it keeps its id and environment, gets a new secret, and the old secret stops working at once. A key that has written entries can be disabled but not deleted, because the entries it wrote name it; the dashboard says so if you try. See API keys.
When a request is refused
| Answer | What it means | What to do |
|---|---|---|
| 401 | The key is missing, not in the public.secret form, unknown, or disabled. The answer carries no code; the SDKs raise InvalidApiKeyError. | Check that the key is set where your code runs and has not been disabled under Settings, Developer, API keys. |
RECORDS_API_NOT_ENABLED (403) | Records are written from a records workspace. | Pick the records option under Settings while the workspace has no committed entry, or ask us to switch the workspace. |
RATE_LIMIT_EXCEEDED (429) | A workspace writes up to 120 entries a minute and shares up to 30 links a minute. Every answer under the limit carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; a 429 carries retryAfterSeconds in the body and a Retry-After header. | Wait that many seconds and send again with the same idempotency key. The SDKs wait and send again on their own, twice by default. |
Who else can read a record
Two things open a record to someone who holds no key of yours. A share link opens the Shared Record in a browser, behind a code you send separately. A grant token lets software read the record's receipts and history with ?grant= and no key; grants are made with POST /api/v1/records/{recordType}/{record}/grants. An outside evaluator's tooling, for example, can read eval-run-4417 with a grant and never hold your key.
Webhooks
PacSpace signs every webhook delivery with your endpoint's signing secret, which is separate from your API key. Check each delivery before you act on it: new Webhooks(secret).verifyFromHeaders(headers, rawBody). See Signature verification.
The dashboard
The dashboard at app.pacspace.io signs in with a browser session. Its routes are described under Dashboard API.