> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velatir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

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

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.

<Steps>
  <Step title="Open your key settings" icon="settings">
    In the dashboard, go to **Settings → API keys**.
  </Step>

  <Step title="Start a new key" icon="plus">
    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](/api/overview#changes-are-attributed-to-the-key).
  </Step>

  <Step title="Choose the API type" icon="toggle-right">
    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.
  </Step>

  <Step title="Set an expiry" icon="calendar">
    Pick an expiration date. It defaults to a year out. A key with no expiry is valid until you revoke it.
  </Step>

  <Step title="Copy the key" icon="copy">
    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.
  </Step>
</Steps>

An API key looks like this, and is about fifty characters long:

```
vltr_api_kJ8nQ2xvR7mBd4TfWpL9aYcE3sHgN6uZqT1rXwB
```

## Send the Key With a Request

Put the key in the `X-API-Key` header:

```bash theme={null}
curl https://api.velatir.com/organisations \
  -H "X-API-Key: vltr_api_your_key_here"
```

`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:

```bash theme={null}
curl https://api.velatir.com/organisations \
  -H "X-API-Key: vltr_api_your_key_here"
```

```json theme={null}
[
  {
    "id": "3f2a91c4-5d8e-4b17-9a63-0c2e7d84fb15",
    "name": "Northwind Legal"
  }
]
```

<Tip>
  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.
</Tip>

## When a Request Is Rejected

| Status | Meaning                                     | What to check                                                                                                                                                                        |
| ------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401`  | The key was not accepted                    | The key is mistyped, revoked, or past its expiry date. All three return the same response, so check the key's status in **Settings → API keys**.                                     |
| `403`  | The key is the wrong kind for this endpoint | Either you sent an ingestion key to an organisation endpoint, or you called something only a signed-in person can do, such as creating a key.                                        |
| `404`  | The resource is not yours                   | The organisation or record id in the path belongs to another organisation. Velatir answers `404` rather than `403` here, so a key cannot be used to probe for what exists elsewhere. |
| `400`  | The request body was rejected               | The response says which field failed.                                                                                                                                                |

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

<Warning>
  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.
</Warning>

***

<CardGroup cols={2}>
  <Card title="Instructions over the API" icon="fingerprint" href="/api/instructions">
    Put the key to work creating and removing instructions.
  </Card>

  <Card title="Roles & permissions" icon="users" href="/platform/roles-and-permissions">
    Who can create a key in the first place.
  </Card>
</CardGroup>