Skip to main content

Creating an API Key

Stealthium uses API keys to authenticate agents running on your machines. This guide shows you how to sign in via the REST API and generate a key entirely from the command line — no UI required after the initial OAuth step.

How Authentication Works​

Stealthium authenticates users through GitHub or Google OAuth only — there is no separate username/password system.

Domain restriction: Only email addresses from approved domains can log in. If you get a domain_not_allowed error, contact your Stealthium administrator to whitelist your email domain.

The flow is:

  1. You open the OAuth login URL in a browser once.
  2. After approving, Stealthium redirects back to your frontend_url with a short-lived token in the URL.
  3. You use that token (a JWT) as a Bearer token for all subsequent API calls, including creating API keys.

Step 1 — Trigger OAuth Login​

Open one of these URLs in a browser, choosing your preferred provider:

GitHub:

https://api.backend.stealthium.io/api/v1/auth/github?frontend_url=http://localhost:5173

Google:

https://api.backend.stealthium.io/api/v1/auth/google?frontend_url=http://localhost:5173

:::info frontend_url The frontend_url is where Stealthium will redirect after login, appending ?token=<JWT>. For local use, http://localhost:5173 works fine. The URL must be on the Stealthium allowlist — if you get an Invalid Frontend URL error, contact your admin to add your URL. :::

After you approve the OAuth prompt, your browser will be redirected to:

http://localhost:5173/auth/callback?token=<YOUR-JWT>

Copy the JWT value from the URL. This is your session token.

Step 2 — Verify Your Session (Optional)​

Confirm the token works and see your user info:

curl -s https://api.backend.stealthium.io/api/v1/me \
  -H "Authorization: Bearer <YOUR-JWT>"

Response:

{
  "user": {
    "id": 1,
    "email": "you@yourcompany.com",
    "name": "Your Name",
    "avatar": "https://..."
  }
}

Step 3 — Create an API Key​

curl -s -X POST https://api.backend.stealthium.io/api/v1/keys/ \
  -H "Authorization: Bearer <YOUR-JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northeast Cluster",
    "description": "Production GPU hosts"
  }'

Response:

{
  "api_key": {
    "id": 42,
    "name": "Northeast Cluster",
    "key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "description": "Production GPU hosts",
    "is_active": true,
    "expires_at": "",
    "last_used_at": "",
    "created_at": "2026-03-19T10:00:00Z",
    "updated_at": "2026-03-19T10:00:00Z"
  },
  "message": "API key created successfully"
}

:::warning Save the key now The key value is returned only at creation time. Copy it immediately. If you lose it, delete the key and create a new one. :::

Step 4 — Use the Key in Your Agent​

Paste the key into your Stealthium agent configuration.

Debian / Ubuntu package​

echo "[orion]" | sudo tee /etc/stealthium/config.toml
echo 'api_key = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"' | sudo tee -a /etc/stealthium/config.toml

Docker environment variable​

docker run -d \
  --name stealthium-agent \
  -e STEALTHIUM_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --restart always \
  --privileged \
  --cap-add NET_ADMIN \
  --pid host \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -v /lib/modules:/lib/modules:ro \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /sys/kernel/tracing:/sys/kernel/tracing \
  -v /run/dbus/system_bus_socket:/run/dbus/system_bus_socket:rw \
  -v /etc/stealthium:/etc/stealthium:rw \
  -v /usr:/usr:ro \
  registry.backend.stealthium.io/stealthium/release:latest

Helm (Kubernetes)​

helm upgrade --install stealthium-agent \
  oci://registry.backend.stealthium.io/stealthium/release/stealthium-agent \
  --version 0.1.2 \
  --namespace stealthium \
  --create-namespace \
  --set stealthium.apiKey=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --set registryCredentials.registry=registry.backend.stealthium.io \
  --set registryCredentials.create=true \
  --set registryCredentials.username=harbor-user \
  --set registryCredentials.password='harbor-password'

Other Key Management Commands​

List all your keys​

curl -s https://api.backend.stealthium.io/api/v1/keys/ \
  -H "Authorization: Bearer <YOUR-JWT>"

Delete a key​

curl -s -X DELETE https://api.backend.stealthium.io/api/v1/keys/<key-id> \
  -H "Authorization: Bearer <YOUR-JWT>"

Troubleshooting​

"domain_not_allowed" after OAuth​

Your email domain is not on the approved list. Ask a Stealthium admin to add your company's email domain to the server allowlist.

"Invalid Frontend URL"​

The frontend_url you passed is not on the server's allowlist. Use an approved URL (e.g. http://localhost:5173 for local use) or ask your admin to add your URL.

GitHub login — no email found​

If your GitHub email is set to private, Stealthium automatically fetches your verified primary email from the GitHub API. Make sure your GitHub account has at least one verified email address.

Lost or compromised key​

  1. List your keys to find the ID: 
    curl -s https://api.backend.stealthium.io/api/v1/keys/ \
      -H "Authorization: Bearer <YOUR-JWT>"
  2. Delete the compromised key: 
    curl -s -X DELETE https://api.backend.stealthium.io/api/v1/keys/<key-id> \
      -H "Authorization: Bearer <YOUR-JWT>"
  3. Create a new key and update your agent configuration.