API Keys

Every call to the Nautilus API from your own backend is authenticated with an API key. This page is the short version; each API's own reference documents its authentication in full, and the links are in the table below.

Create a key

Keys are created and revoked on the Dashboard → Keys page. When you create one you name it and tick the APIs it may call: one, several, or all four. Tick only what the key needs, so that a key in a mobile app or a staging server cannot do more than that.

A key cannot be changed afterwards. To give a key more reach, create a new one, deploy it, and revoke the old one.

A key belongs to one tenant. The tenant is taken from the key itself, never from the request, so a caller can only read and change its own tenant's data.

The key is shown once, when you create it. Copy it then.

Send it

A key looks like vrn_ followed by random characters, and it does not name an API. Send it as a Bearer token in the Authorization header, to the single API host:

curl https://api.vernesoft.com/v1/relay/messages \
  -H "Authorization: Bearer vrn_9f8a7..."

Server-side only. API keys carry full access to the APIs they were created for. Never ship one to a browser, a mobile app, or a WASM bundle.

One scope per API

What a key may call is its set of scopes, one per API. A call to an API the key has no scope for is refused with 403 Forbidden, and the body is the same on every API apart from the name in the message:

{
  "error": {
    "code": "forbidden",
    "message": "This API key is not authorized for Clockwork.",
    "request_id": "req_..."
  }
}

message ends with the API's name: Relay, Gate, Clockwork or Passepartout. Branch on error.code and the status, and show message to a person.

Older keys

Keys created before scopes existed have the API in their name: vrn_gate_..., vrn_relay_..., vrn_clockwork_..., vrn_passepartout_.... They keep working and open exactly the one API they name, so a deployed key does not need to be replaced.

There is no sandbox mode

A key has no test or live environment, and no key puts an API into a sandbox. Every key acts on the tenant's real data. To tell development and production callers apart, create a separate key for each.

The full list of routes, with the authentication each one needs, is on All Endpoints. The official SDKs take the key once and add the header for you; see Installation.

Plans

What your plan limits (active users, Relay messages, Clockwork jobs) is separate from the key, and so is what a call receives when a limit is reached. That is on Plans, Limits and Refusals. Prices are on the pricing page.