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 ingestion key, not an API key. Start from the quickstart instead.

​
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 ingestion endpoints, and an ingestion 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.
Access is also all-or-nothing today. There is no way yet to issue a key that can only read, or one limited to a single endpoint. Where that matters, issue a separate key per system so you can revoke one without disturbing the others.

​
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.