Authentication
Authenticate every request with an API key, and grant each key only the scopes it needs.
Every request to the Vestta API is authenticated with an API key. A key belongs to one Vestta workspace: everything the API returns or creates is scoped to that workspace, and the key's scopes decide which endpoints it may call.
Keys are created and managed in the Vestta app — see API keys.
Sending the key
Send the key in the X-Api-Key header:
For compatibility with existing integrations, the API also accepts the key in the Authorization header with the ApiKey scheme:
Use X-Api-Key in new integrations. When both headers are present, X-Api-Key is used and Authorization is ignored.
Key format
Keys look like this:
key_id identifies the key and is visible in the Vestta app; secret is shown only once, when the key is created. Vestta stores a hash of the secret, never the secret itself, so a lost key cannot be recovered — create a new one.
Scopes
A scope grants access to a group of endpoints. Scopes are chosen when the key is created (under Permisos in the Vestta app) and cannot be changed afterwards; to change them, create a new key.
This is how scopes map to endpoints, as declared in the OpenAPI schema:
How a request is checked
The API checks a request in this order, and stops at the first failure:
- The key — present, well formed, known, active, not expired, with a matching secret. Otherwise:
401. - The parameters and body — validated against the schema. Otherwise:
422. - The scope — the key must have the endpoint's scope. Otherwise:
401withLack of permissions.
Because parameters are validated before the scope, a key without the right scope can still get a 422 for an invalid request. Missing scopes are reported as 401, not 403.
Each 401 has a specific message that tells you what failed. They are listed in Errors.
Where to call the API from
Call the API from your server, not from the browser. The API answers cross-origin requests, but any key used in front-end code is visible to every visitor and can be copied.
To send leads from a public website, post the form to your own backend and call Create an inquiry from there, keeping the key in a server-side environment variable.