Authenticate with an API Key

Every request to the VIS API sends an API Key. The gateway uses it to identify your Application and to apply its Quota.

Send the key

Send the secret, exactly as the portal showed it, in the X-Api-Key header:

curl "$VIS_API_URL/..." -H "X-Api-Key: $VIS_API_KEY"

Send the header once. The gateway answers:

• 401 api_key_required when the route needs a key and the request has none;
• 401 invalid_api_key when the key is unknown or revoked;
• 400 invalid_api_key_header when the header is malformed or repeated.

See Gateway errors for the complete list.

Keep the key on your servers

An API Key is meant for servers that can keep a secret. Store it in your secret store or environment, never in your source code.

A key embedded in a browser front-end or a mobile app is readable by anyone who loads it. Treat such a key as public: anyone can copy it and send requests that count against your Quota. Call the VIS API from your servers instead.

Rotate a key

An Application has at most two active API Keys, so you can replace a key without downtime:

1. Create a second key, and deploy its secret to your servers.
2. Check that your requests succeed with the new key.
3. Revoke the old key.

Regenerate replaces the secret of a key and keeps its public ID. The page shows the new secret once. The old secret stops working within seconds, so clients that still use it are rejected until they switch. The keys of a suspended Application cannot be regenerated, only revoked.

Revoke stops a key for good. A revoked key no longer counts toward the limit of two active keys.

Who can manage keys

Owners and Admins of an Organization create, regenerate, and revoke its API Keys. Members see each key's label, ID, and status, but cannot change them. Nobody can see a secret after the page that created or regenerated it. See Organizations and roles.