Authentication

Authenticate every request with an API key, and grant each key only the scopes it needs.

On this page

Sending the key
Key format
Scopes
How a request is checked
Where to call the API from

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:

Terminal

curl "https://api.vestta.app/v1/me" \
  -H "X-Api-Key: $VESTTA_API_KEY"

For compatibility with existing integrations, the API also accepts the key in the Authorization header with the ApiKey scheme:

Terminal

curl "https://api.vestta.app/v1/me" \
  -H "Authorization: ApiKey $VESTTA_API_KEY"

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:

Text

AC_LIVE_<key_id>.<secret>

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.

Scope	In the Vestta app	Grants
`properties:read`	Propiedades	Read the public property catalogue.
`properties:write`	Editar propiedades	Create and update properties and upload photos.
`properties:publish`	Publicar propiedades	Publish, unpublish and read processing state.
`leads:write`	Editar contactos	Create and update private CRM contacts without outreach.
`leads:read`	Leer leads	Read every lead of the workspace, including contact details.
`leads:ingest`	Enviar consultas	Create leads from your forms and services.

This is how scopes map to endpoints, as declared in the OpenAPI schema:

Scope	Endpoints
`leads:ingest`	POST/v1/leads/ingest POST/v1/leads/inquiries
`leads:read`	GET/v1/leads GET/v1/leads/{lead_id}
`leads:write`	POST/v1/leads PATCH/v1/leads/{lead_id}
`properties:publish`	GET/v1/properties/{property_id}/publication PUT/v1/properties/{property_id}/publication
`properties:read`	GET/v1/properties GET/v1/properties/{property_id}
`properties:write`	POST/v1/properties PATCH/v1/properties/{property_id}POST/v1/properties/{property_id}/images/uploads POST/v1/properties/{property_id}/images/uploads/{upload_id}/complete
None — any active key	GET/v1/me

How a request is checked

Every operation verifies authentication, the required scope and its request schema:

The key — present, well formed, known, active, not expired, with a matching secret. Otherwise: 401.
The scope — the key must have the endpoint's scope. Otherwise: 403 with Insufficient scope.
The parameters and body — validated against the schema. Otherwise: 422.

Do not depend on error precedence when a request fails more than one check. Authentication errors use 401, insufficient scopes use 403, and invalid input uses 422.

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.