Authentication

All /api/v1/* endpoints require authentication via JWT bearer token.

Token Format

Constellation uses JWT (JSON Web Token) with HS256 signing algorithm.

Request Header

Authorization: Bearer <token>

Token Payload

{
  "sub": "operator",
  "operator_id": "acme-corp",
  "operator_name": "ACME Corporation",
  "scopes": ["read", "write"],
  "iat": 1705430400,
  "exp": 1737052800
}

Claim	Type	Description
`sub`	string	Subject (always “operator”)
`operator_id`	string	Unique operator identifier
`operator_name`	string	Human-readable name
`scopes`	string[]	Permission scopes
`iat`	number	Issued at (Unix timestamp)
`exp`	number	Expiration (Unix timestamp)

Scopes

Scope	Permissions
`read`	Read topology, predictions, models
`write`	Post telemetry
`telemetry:write`	Post telemetry data
`telemetry:read`	Read telemetry history
`topology:read`	Read network topology
`predictions:read`	Read predictions

Getting a Token

Via CLI

constellation login

This opens your browser for OAuth authentication and stores the token locally.

Via Dashboard

Log in at dev.constellation-io.com/dashboard
Navigate to Settings → API Tokens
Click “Generate Token”
Copy the token (shown only once)

Manual Token Generation (Admins)

python -m scripts.generate_operator_token \
  --operator-id acme-corp \
  --operator-name "ACME Corporation" \
  --aws-secret-arn "arn:aws:secretsmanager:us-west-2:...:secret:constellation/prod/jwt-secret" \
  --expires-days 365 \
  --output json

Error Responses

Missing Token (401)

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Missing authentication token"
  }
}

Invalid Token (401)

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or expired token"
  }
}

Insufficient Scope (403)

{
  "success": false,
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "Missing required scope: write"
  }
}

Token Storage

CLI

Tokens are stored at ~/.constellation/credentials:

access_token: eyJhbGciOiJIUzI1NiIs...
refresh_token: eyJhbGciOiJIUzI1NiIs...
expires_at: 2027-01-16T00:00:00Z

Dashboard

Tokens are stored in localStorage and automatically refreshed.

Token Refresh

Access tokens expire after 1 hour. Use the refresh token to get a new access token:

curl -X POST https://auth.constellation-io.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=constellation-cli" \
  -d "refresh_token=$REFRESH_TOKEN"

Public Endpoints

The following endpoints do NOT require authentication:

Endpoint	Description
`GET /health`	Health check
`GET /docs`	Swagger UI
`GET /redoc`	ReDoc documentation
`GET /api/v1/benchmark/results`	Benchmark results
`GET /api/v1/benchmark/stream`	Benchmark SSE stream