API keys

An API key authenticates your backend without a password. The key is your integrator identity: the server resolves your integrator organization from it, which is why the integrator endpoints take no address in the path. Each key carries a set of scopes and an optional expiry, and can be revoked at any time.

Create your keys in the API Dashboard; API keys can only be created under integrator organizations. The full secret is shown only once, at creation - store it in your secret manager immediately. Afterwards only the key metadata (id, prefix, scopes and timestamps) is available.

¶Using a key

Send the key as a bearer token on every request, exactly like a session token - the same header for every call in this documentation. The plaintext secret is prefixed vsk_; the prefix (e.g. vsk_ab12) is safe to log for identification, the full secret is not.

curl "https://saas-api-stg.vocdoni.net/organizations/$ORG/processes" \
  -H "Authorization: Bearer vsk_your_api_key"

A key works only on endpoints its scopes allow, and only on the organization that owns it.

¶Scopes

A key only works on an endpoint if it carries the right scope. Scopes are deny-by-default, so mint keys with exactly what the integration needs.

The election lifecycle inside a managed org is split across members:write (members and groups) and voting:write (census, process, bundle, vote relay), so an integration that runs a vote end to end needs both, in addition to the managed:* scopes it uses to provision the org. An admin user logging in with email/password carries these implicitly; an API key must be granted each one explicitly.

¶Managing keys

Review and revoke keys in the API Dashboard. The same operations are available programmatically for multi-tenant provisioning:

curl "${auth[@]}" "$B/organizations/$ORG/apikeys"                  # list
curl "${auth[@]}" -X DELETE "$B/organizations/$ORG/apikeys/$KEYID" # revoke

Listing returns only metadata (id, prefix, scopes, timestamps) - never the secret.

¶Authentication failure modes