Skip to main contentCertyo Developer Portal

Authentication

Every public API request is authenticated with an API key in the X-API-Key header.

The X-API-Key header

Certyo API keys are opaque strings prefixed with certyo_sk_live_ (production) or certyo_sk_test_ (sandbox). Include them on every request:

curl https://www.certyos.com/api/v1/records \
  -H "X-API-Key: certyo_sk_live_abc123..."

Scope & what an API key grants

An API key is bound to a specific tenant and client. It can:

  • Ingest records under its tenant
  • Query records under its tenant
  • Verify records under its tenant
  • Access verification history and audit logs for its tenant

Keys cannot cross tenant boundaries. An Acme Corp key cannot read records from Globex Corp, even if they exist in the same database or collection name.

Key storage

Never commit API keys
Don't paste keys into source code, CI config, or test fixtures. Use environment variables or a secrets manager.

Recommended storage by platform:

  • Node.js / Python / Go apps — environment variables, e.g. CERTYO_API_KEY
  • Kubernetes — K8s Secrets mounted as env vars
  • AWS — Secrets Manager or Parameter Store
  • GCP — Secret Manager
  • Azure — Key Vault

Key rotation

Keys don't expire automatically, but you should rotate them periodically (we recommend every 90 days) or immediately if compromise is suspected.

  1. In the backoffice, generate a new key for the same client.
  2. Update your applications to use the new key (deploy in parallel).
  3. Once all traffic is using the new key, deactivate the old one.

Both keys work during the rollover window, so there's no downtime.

What to do if a key is compromised

  1. Deactivate it immediately from the backoffice. The key stops working within seconds.
  2. Generate a replacement key and roll it out.
  3. Audit recent activity — use GET /api/v1/audit/history to see which records were ingested or verified with the compromised key.

Common errors

  • 401 Unauthorized — missing or invalid API key. Check the X-API-Key header is present and the key is active.
  • 403 Forbidden — key is valid but doesn't have access to the requested tenant or resource.
  • 429 Too Many Requests — you hit the client's rate limit. Back off and retry with exponential backoff.