Skip to main content

Authentication

Sending the key​

Every request to the /v1 routes needs the API key in the Authorization header:

Authorization: Bearer vld_live_7crbnGcZZEHpGN8PQ2j7tSOZKPEVhkpWMoVFbXgxbjm

If your tool cannot set that header, use X-API-Key with the same key:

X-API-Key: vld_live_7crbnGcZZEHpGN8PQ2j7tSOZKPEVhkpWMoVFbXgxbjm
Never send the key in the URL

Requests with the key in the URL (for example ?api_key=) are refused with a 401 error. URLs end up in browser histories, server logs and proxies.

Key format​

Keys start with vld_live_, followed by 43 letters and numbers. The prefix helps secret scanning tools (such as GitHub's) recognize a key published by mistake.

Validades only stores a fingerprint (hash) of the key. That is why it is shown only once and cannot be recovered.

The key belongs to the organization​

The key belongs to the organization, not to the person who created it. If that person leaves the organization, the key keeps working until it is revoked. The panel shows who created each key.

Everything done with the key shows up in the organization's activity log as "Via API (key "Name")".

Scopes​

ScopeAllows
readevery query (GET)
writecreating (POST) and updating (PATCH)
deletedeleting (DELETE)

A call without the required scope gets 403 with the insufficient_scope code, and the details.required_scope field tells which scope was missing.

Give each integration only what it needs. An integration that only reads batches should not have write or delete.

Expiration and revocation​

  • When creating a key, you can set an expiration (30, 90, 180 or 365 days). After that it stops working.
  • In the panel, Revoke disables the key immediately. Integrations using it start getting 401.
  • To replace a key without stopping the integration: create the new one, update your system and only then revoke the old one. That is why the limit is 5 active keys.

If a key leaks​

  1. Revoke the key immediately in the panel (validades.com → Team → API).
  2. Create a new key and update your integration.
  3. Check the calls made with the old key in Logs and usage (date, route, IP).
  4. If you find something odd, contact support with the request_id of the calls.

Remember that, under the API Terms of Use, everything done with a valid key of the organization is considered done by the organization.

Access errors​

SituationHTTPcode
Missing, invalid, revoked or expired key401invalid_api_key
API not enabled for the organization403api_access_not_enabled
Access suspended403api_access_suspended
Personal workspace (not an organization)403workspace_not_eligible
New version of the terms not accepted after the deadline403terms_not_accepted
Organization without an active subscription402subscription_inactive
Key without the required scope403insufficient_scope

Without an active subscription, the API answers no requests at all, not even reads. It works again as soon as the subscription is renewed.