Skip to main content

Authentication

Every request to the Stealthium REST API is authenticated with a bearer token in the Authorization header:

curl "https://api.stealthium.io/api/v1/alerts/" \
  -H "Authorization: Bearer <YOUR-JWT>"
Two hosts, one token

Stealthium's REST surface spans two services that accept the same JWT:

  • https://api.backend.stealthium.io — auth, /me, API keys, workspaces
  • https://api.stealthium.io — alerts, GPUs, metrics, MCP

Each endpoint's docs show the right host. Browsers can also authenticate with the auth_token HttpOnly cookie the web app sets — the header wins if both are present.

Getting a token​

Sign in with GitHub or Google as described in Creating an API Key. After login you are redirected to your frontend_url with a single-use ?code=<auth-code> query parameter; exchange it for the JWT:

curl -s -X POST https://api.backend.stealthium.io/api/v1/auth/token \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"code": "<AUTH-CODE>", "redirect_uri": "<your frontend_url>"}'

The response's access_token is your bearer token. See the full walkthrough for details and caveats (codes expire in ~1 minute and are single-use).

Agent API keys don't work here

API keys authenticate Hyperion agents, not the REST API. Requests to the endpoints in this section must use the JWT from the OAuth login flow.

Token expiry and refresh​

Access tokens last 6 hours. When one starts returning 401, redeem your refresh token instead of logging in again:

curl -s -X POST https://api.backend.stealthium.io/api/v1/auth/refresh \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"refresh_token": "<YOUR-REFRESH-TOKEN>"}'

Response: {"access_token": "...", "token_type": "Bearer", "expires_in": 21600}.

Refresh tokens last 24 hours and are not extended by use, so a session lives at most 24 hours before you must sign in again.

Authentication errors​

A missing, expired, or invalid token returns 401 Unauthorized. The two services word it differently:

From api.stealthium.io (alerts/GPUs/metrics):

{
  "error": "unauthorized",
  "message": "missing auth token"
}

From api.backend.stealthium.io (auth/keys/workspaces):

{
  "title": "Unauthorized",
  "detail": "..."
}