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
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
| Scope | Allows |
|---|---|
read | every query (GET) |
write | creating (POST) and updating (PATCH) |
delete | deleting (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
- Revoke the key immediately in the panel (validades.com → Team → API).
- Create a new key and update your integration.
- Check the calls made with the old key in Logs and usage (date, route, IP).
- If you find something odd, contact support with the
request_idof 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
| Situation | HTTP | code |
|---|---|---|
| Missing, invalid, revoked or expired key | 401 | invalid_api_key |
| API not enabled for the organization | 403 | api_access_not_enabled |
| Access suspended | 403 | api_access_suspended |
| Personal workspace (not an organization) | 403 | workspace_not_eligible |
| New version of the terms not accepted after the deadline | 403 | terms_not_accepted |
| Organization without an active subscription | 402 | subscription_inactive |
| Key without the required scope | 403 | insufficient_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.