Authentication

Two credential types, used in sequence: an API key you manage in the app, and a short-lived access token you get from it.

API keys

Created from Vault → API Keys → Add in the OneGuard app. A key:

• Starts with og_ and is shown only once — the app stores only a hash, so a lost key can't be recovered, only revoked and replaced.
• Has a permission of read or write, checked on every request. A read key can list and fetch; a write key can also create, change, and delete.
• Has an expiry you set when creating it.
• Can be rotated or turned off from the same API Keys screen, without affecting other keys.

A key is never sent on any request except the one below.

Exchanging a key for a token

curl -s https://api.oneguard.one/v1/auth/token \
  -X POST \
  -H "Authorization: Bearer og_your_key"

{
  "statusCode": 200,
  "errorCode": null,
  "message": null,
  "data": {
    "access_token": "ogt_eyJhbGciOi...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expires_at": "2026-09-23T15:04:05.000Z"
  }
}

The key is read from the Authorization header only — never from the request body or a query string. Every other /v1 request uses the resulting ogt_... token the same way:

curl -s https://api.oneguard.one/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

Token lifetime

An access token is valid for expires_in seconds (currently 3600, i.e. 60 minutes) from expires_at. There is no separate refresh endpoint — when a token expires, exchange the API key again the same way you did the first time. The response is a completely fresh token each time, so nothing is invalidated by fetching a new one early.

A key's permission is re-checked from its current value on every request, not copied into the token at exchange time. Disabling or downgrading a key takes effect immediately, even for tokens already issued from it.

What 401 means mid-session

{
  "statusCode": 401,
  "errorCode": "unauthorized",
  "message": "...",
  "data": null
}

with a WWW-Authenticate: Bearer header. This happens when the token has expired, the key behind it was disabled or deleted, or the Authorization header is missing or malformed. The fix is always the same: exchange the key again for a new token.

Rotating and revoking a key

Regenerating or disabling a key is done from Vault → API Keys in the app, not through this API.

• Disabling a key: tokens already issued from it stop working within about 30 seconds (the server caches key status briefly to avoid a database lookup on every request).
• Regenerating a key: issues a new og_... value. A token exchanged just before the regeneration keeps working for a short grace window afterward, so an in-flight request is not dropped mid-rotation — but exchange the new key and switch to it as soon as you have it.

Either way, the key itself is never deleted by this — it is disabled or replaced, still visible (and re-enableable, for a disable) from Vault → API Keys.