API Authentication

The Arctic API uses OAuth2 client credentials for authentication.

Getting Credentials

Credentials are obtained during bootstrap or created via the credentials API.

During Bootstrap

curl -X POST http://agent:8080/v1/bootstrap \
  -H "Content-Type: application/json" \
  -d @license.json

The response includes client_id and client_secret.

Via Credentials API

curl -X POST http://agent:8080/v1/credentials \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["urn:tillered:arctic:peers.read"]}'

See Credentials API for details.

Token Request

Exchange credentials for an access token:

curl -X POST http://agent:8080/v1/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using Tokens

Include the token in the Authorization header:

curl -X GET http://agent:8080/v1/peers \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Token Expiration

Tokens expire after 1 hour (3600 seconds). Request a new token when the current one expires.

Scopes

Credentials can be limited to specific scopes:

Scope	Description
`urn:tillered:arctic:admin`	Full access
`urn:tillered:arctic:peers.read`	Read peers
`urn:tillered:arctic:peers.write`	Modify peers
`urn:tillered:arctic:services.read`	Read services
`urn:tillered:arctic:services.write`	Modify services
`urn:tillered:arctic:credentials.read`	Read credentials
`urn:tillered:arctic:credentials.write`	Modify credentials

OIDC Discovery

The API provides standard OIDC discovery endpoints:

Discovery Document

curl http://agent:8080/.well-known/openid-configuration

JWKS

curl http://agent:8080/.well-known/jwks.json

Error Responses

401 Unauthorized

Token missing, invalid, or expired:

{
  "error": "unauthorized",
  "code": "UNAUTHORIZED"
}

403 Forbidden

Token valid but insufficient scope:

{
  "error": "insufficient scope",
  "code": "FORBIDDEN"
}

Public Endpoints

These endpoints do not require authentication:

GET /livez
GET /readyz
GET /.well-known/openid-configuration
GET /.well-known/jwks.json
GET /v1/cluster/identity
POST /v1/oauth/token
POST /v1/bootstrap

Authentication

On this page