Authentication

The Sivo API uses API keys to authenticate requests. Send your key as the value of the Authorization header on every request:

curl https://core.sivo.com/me \
  -H "Authorization: $SIVO_API_KEY"

GET /me returns the organization and caller behind the key, which makes it a quick way to check that a key works.

Your API keys

Create and manage API keys in the Sivo dashboard under Connections → API Keys. Only organization admins can see or manage keys.

Every key belongs to one environment, and its prefix tells you which one:

To create a key, click Create API Key, give it a name that says where it will be used (for example Production - Web App), and pick its environment. The full key is shown only once, when you create it. Copy it straight into your secrets store. After that, the dashboard shows only a masked copy (sk_live_...a1b2), and Sivo can't recover the full key for you.

You can create as many keys as you need. Use a separate key for each application or service, so you can revoke one without affecting the others.

Sending your key

Send the key itself as the whole value of the Authorization header:

Authorization: sk_snbx_...

In TypeScript:

const response = await fetch('https://core.sivo.com/me', {
  headers: { Authorization: process.env.SIVO_API_KEY },
});

Make every request over HTTPS. The base URL is the same for both environments, and the key you send decides whether a request reaches sandbox or live data.

What a key can do

A key acts on behalf of the organization that created it, with an admin's access. It can read and write all of that organization's data in its environment. Keys have no scopes and don't expire: a key works until you delete it.

Treat your keys like passwords:

• Keep keys on your servers. Never put a key in a web page, mobile app, or anything else that runs on your users' devices, and never commit one to source control.
• Store keys in a secrets manager such as AWS Secrets Manager, Google Secret Manager, or HashiCorp Vault. If your platform has no secrets manager, use environment variables.
• Use sandbox keys for development. Keep live keys out of local machines, test suites, and CI.
• Limit who can manage keys. Anyone who is an admin in your Sivo organization can create and delete keys.

Rotating and revoking keys

Deleting a key in the dashboard revokes it immediately. Any request that still uses it fails with 401 Unauthorized, and deleting can't be undone.

To rotate a key without downtime:

1. Create a new key in the same environment.
2. Deploy the new key to your application and confirm requests succeed with it.
3. Delete the old key.

If a key may have leaked, delete it right away, then create and deploy a replacement.

Authentication errors

Both return the standard error object:

{
  "message": "Unauthorized"
}

A 401 means the key is the problem, so retrying with the same key won't help. Check that you copied the full key, that it hasn't been deleted, and that it's for the environment you meant to use.