Skip to content
vendorvett.

API authentication

API keys are a Business-plan feature (public_api). Only an owner can create or revoke one, from Settings → API. The token is shown once, in the create response, and is not stored in a form that can be shown again.

Header

Authorization: Api-Key vvk_<prefix>_<secret>

The scheme is Api-Key, then a space, then the token. The token always starts with vvk_. The MCP server also accepts Authorization: Bearer vvk_… on its own URL. Other routes do not treat Bearer as an API key.

Create a key

In Settings → API, an owner names the key and chooses access: read or write. The same call is POST /api/orgs/ORG/api-keys/ with a JSON body. A scope other than those two is stored as read. The name defaults to "API key" and is cut at 100 characters.

curl -s -X POST "https://api.vendorvett.com/api/orgs/ORG/api-keys/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Warehouse sync","scope":"read"}'

Creating a key is an owner action in the signed-in app, so that example uses the session access token from sign-in, not an API key. The 201 body includes token once, plus id, prefix, scope and name. Copy the token then. Later responses list the prefix only.

Revoke with DELETE /api/orgs/ORG/api-keys/ID/. That returns 204, including when the key was already revoked.

Scope, role and lifetime

A key is allowed to do only what all of the following allow:

  • It calls only /api/orgs/<its organization>/. Any other path, including another tenant's, is rejected.
  • A read key may use safe methods (GET, HEAD, OPTIONS). A write is rejected. The MCP endpoint is the exception: its POST only reads, so a read key may call it.
  • A write key may write, and still only where the member who created it could. Vendor and assessment writes need an analyst or an owner. Audit-log reads need an owner. Creating keys needs an owner.
  • The key stops when an owner revokes it, when the creator is no longer an active member, or when the organization's plan no longer includes the API.

The database stores a SHA-256 digest of the token. A request that presents a key is limited to 120 requests a minute for that key. See Errors and rate limits.