Skip to main content
Velatir’s dashboard is a client of a public HTTP API, and your own systems can call that same API. Use it when a rule in Velatir should follow something your business already knows — a project becoming confidential, a supplier being onboarded, a team changing scope — instead of waiting for someone to remember to update it by hand. The API is reached at:

​
Two Kinds of Key

Velatir has two key types, and they are not interchangeable. Both are created on the same settings page, which is why it is worth being precise about which one a task needs.
An API key carries administrator-equivalent access to everything in your organisation. Anyone holding it can read your traces and change your agent configuration. Treat it like an administrator’s password, not like a deployment setting: keep it in a secret store, never in source control or a browser, and revoke it the moment you suspect it is exposed.
If you are rolling Velatir out to people’s devices, you want an ingest key, not an API key. Start from the quickstart instead.

​
Scopes

Scope decides where a key’s activity or authority lands. It is not a permission list.
Choose Organisation or one workspace when you create the key.Organisation covers the whole organisation. Generate ingest key on the Setup page creates this kind of key, and it is the one to roll out to a fleet.Workspace sends that key’s activity into the one workspace you chose. Create it under Settings → API keys after the workspace exists. Use it to roll out to a single workspace, or to keep that workspace’s activity separate.Either scope can only submit telemetry. An ingest key cannot read traces or change configuration.
An API key is always Organisation. The scope cannot be narrowed to a workspace.There is also no finer permission scope. You cannot issue a read-only API key, or one limited to a single endpoint. Where that matters, create a separate key per system so you can revoke one without disturbing the others.What the key can do is administrator-equivalent access to the organisation API, apart from the actions reserved for a signed-in person, described below.

​
What You Can Do With an API Key

An API key reaches the organisation endpoints as an administrator. In practice that covers reading your traces, assessments, and agents, and managing instructions — the main reason customers automate against Velatir. Some things are deliberately closed to an API key:
  • Creating keys. Only a signed-in person can create a key, so a leaked key cannot mint itself a replacement or quietly widen its own foothold.
  • Submitting activity. An API key is rejected by the ingest endpoints, and an ingest key is rejected by the organisation endpoints. Neither can stand in for the other.
An API key can revoke keys, including your others. Revoking is an administrator action and a key holds administrator access. Combined with the above, a leaked key cannot create a new credential, but it can take your existing ones away — one more reason to keep it in a secret store and revoke it promptly if it is exposed.

​
Changes Are Attributed to the Key

Anything an API key changes is recorded against the name you gave the key, not against a person and not as an anonymous system actor. A key named roadmap-sync produces an audit trail that reads clearly a year later; one named test does not. Give each integration its own key, named for the system that holds it.

Authentication

Create a key, send it with a request, and find your organisation id.

Instructions over the API

Create, update, and remove instructions programmatically.