Skip to main content
Every call to the Velatir API carries an API key. This page takes you from no key to a working request.

​
Create an API Key

You need the organisation Administrator role. Keys are created by a person, never by another key.

Open your key settings

In the dashboard, go to Settings → API keys.

Start a new key

Select Create API key, and give it a name. Name it for the system that will hold it: the name is how the key’s changes are attributed in the audit trail.

Choose the API type

Set Type to API. This is the step that matters: the field defaults to Ingestion, which produces a telemetry key that the endpoints in these pages will reject.Scope is fixed to Organisation for an API key and cannot be narrowed to a workspace.

Set an expiry

Pick an expiration date. It defaults to a year out. A key with no expiry is valid until you revoke it.

Copy the key

The full key is shown once, on creation. Copy it into your secret store before closing the dialog — it cannot be retrieved afterwards, and the listing only ever shows the last four characters. If you lose it, revoke the key and create another.
An API key looks like this, and is about fifty characters long:

​
Send the Key With a Request

Put the key in the X-API-Key header:
Authorization: Bearer vltr_api_your_key_here works too, if a bearer header is easier in your HTTP client. The two are equivalent; if you send both, X-API-Key wins.

​
Find Your Organisation Id

Almost every endpoint is rooted at your organisation, so you need its id for the path. Ask for it with GET /organisations. A key belongs to exactly one organisation, so this returns exactly one entry — its own:
Treat this as your first call when setting an integration up, then store the id in configuration alongside the key. It never changes, so there is no need to look it up on every request.

​
When a Request Is Rejected

​
Rotating and Revoking

Revoke a key from Settings → API keys. Revocation takes effect immediately — there is no grace period and no cached window during which the old key keeps working. To rotate without downtime, create the replacement first, deploy it, and revoke the old key once nothing is using it. Creating the replacement has to be done by a person in the dashboard, because no key can create a key.
Revoking a key cannot be undone, and the key it replaces cannot be recovered. If you revoke the wrong one, you will need to create a new key and update whatever was holding it.

Instructions over the API

Put the key to work creating and removing instructions.

Roles & permissions

Who can create a key in the first place.