Getting an API key

Every /v1 request is authenticated by a bearer key. This page is how you get one.

Note

There is no endpoint that mints a key. Key management lives in the application, behind a signed-in session, and is deliberately absent from the public API — a credential that can issue further credentials turns one leaked secret into an unbounded one. So the first key is always created by a person, in a browser.

Issue one

1. Sign in to app.vendorica.com as a user whose role already carries the permissions you want the key to have.

2. Open Settings → API keys (app.vendorica.com/settings/api-keys).

3. Create key, and fill in:

   Field
   Name	Required. Name it after the integration, not the person — Splunk audit export, not Marc's key. It is what you will be reading in the audit log a year from now.
   Scopes	Required, at least one. See choosing scopes below.
   Acts for	Optional, defaults to you. The person the key acts on behalf of — see why a key names a person.
   Description	Optional, up to 2000 characters. Where it runs, who owns it, what breaks if you revoke it.
   Expires in	Optional, 1–3650 days. Absent means no expiry.
   Rate limit	Optional override, requests per minute. Leave it alone unless you have measured a reason.

4. Copy the key. It is shown once, on this screen, and never again.

A key looks like this — the literal prefix vnd_live_ followed by 32 random base62 characters:

vnd_live_4kQ2mZpX8vNhR7dTgW1yB6cJfL0sAeUi

Caution

Vendorica cannot show you the key again, and cannot recover it. Only a bcrypt hash is stored, plus the first 24 characters in the clear so a lookup can find the right row. If you close the dialog without copying it, the key is not lost data — it is simply gone, and you delete it and issue another.

Put it straight into a secret manager. Not a .env committed by accident, not a CI log, not a Slack message to yourself.

Choose the narrowest scopes

A key holds an explicit set of resource:action scopes, fixed at issue time. Each endpoint requires exactly one, and the reference names it on every operation.

Grant only what the integration calls. A SIEM export that reads the audit log needs audit:read and nothing else — giving it vendors:write because it was convenient means a compromised log shipper can rewrite your vendor register.

The full list is on Authentication.

Note

A key can never exceed its issuer. Scopes are validated against the issuing user’s own role at creation, so an analyst cannot mint a key that does what an administrator can.

The corollary is easy to miss: a key outlives the issuer’s access. It keeps working after they change role or leave the company. Review keys when people move.

Why a key names a person

A key is a machine actor with no user row of its own, but parts of the platform require a person — an incident filed over /v1, for instance, has non-nullable owner columns pointing at users, and somebody has to be notified when one arrives.

So every key names the human it acts for. It defaults to whoever issued it, which is the honest answer for most integrations. Point it at a shared inbox’s user or an on-call lead when the issuer is not the right person to wake up.

Rotation

A key holds exactly one secret for its whole life. There is no “regenerate” that leaves the key in place, which means rotation is deliberately a two-step with an overlap you control:

1. Issue a second key with the same scopes and a name that says what it replaces.
2. Deploy the new secret. Confirm traffic has moved — the audit log attributes calls to the key that made them.
3. Delete the old key.

Doing it in that order means there is no window where the integration has no working credential. Deleting first and issuing second gives you an outage the length of your deploy.

Rotate on a schedule you decide, and immediately if a key has been exposed — in a repository, a log, a screenshot, a support ticket.

Revoking

Delete the key in Settings → API keys. It stops working on the next request; there is no propagation delay to wait out.

Deleting a key does not delete what it did. Audit entries keep pointing at it, which is the whole reason keys are named after integrations.

Checking a key works

curl -sS https://api.vendorica.com/v1/vendors?limit=1 \
  -H "Authorization: Bearer $VENDORICA_API_KEY"

A 200 with an envelope means the key and the vendors:read scope are both good.

A 401 does not always mean the key is wrong. Key authentication runs before routing, so a request to a /v1 path that does not exist is refused as Invalid API key rather than 404. If you are confident in the credential, check the path against the API reference before you go looking at the key.

A 403 is the opposite problem: the key is valid and the scope is missing.