Docs/REST API Reference

REST API Reference

Complete reference for SatGate gateway REST API endpoints.

Authentication: Admin endpoints use X-Admin-Token header. Agent endpoints use Authorization: Bearer <macaroon>. The Mint exchange endpoint accepts a JWT in the request body.

POST/api/capability/mint

Mint a new capability token (macaroon) with specified caveats.

Auth: X-Admin-Token

Request Body

{
  "identifier": "agent-001",
  "caveats": ["scope = api:read", "budget = 100"],
  "ttl": "1h"
}

Response

{
  "token": "MDAxY2...",
  "identifier": "agent-001",
  "caveats": ["scope = api:read", "budget = 100"],
  "expiresAt": "2026-03-01T12:00:00Z"
}
POST/api/capability/validate

Validate a capability token and return its caveats, identity, and remaining budget.

Auth: Bearer <macaroon>

Request Body

{
  "token": "MDAxY2..."
}

Response

{
  "valid": true,
  "identifier": "agent-001",
  "caveats": ["scope = api:read", "budget = 100"],
  "budgetRemaining": 50,
  "expiresAt": "2026-03-01T12:00:00Z"
}
POST/api/capability/delegate

Delegate a child token from an existing parent. The child inherits the parent's caveats and can add further restrictions.

Auth: Bearer <parent-macaroon>

Request Body

{
  "parentToken": "MDAxY2...",
  "additionalCaveats": ["scope = api:read:subset", "budget = 25"],
  "ttl": "30m"
}

Response

{
  "token": "MDAxY2...(child)",
  "parentId": "abc123",
  "caveats": ["scope = api:read:subset", "budget = 25"],
  "expiresAt": "2026-03-01T12:30:00Z"
}
GET/api/capability/ping

Verify gateway connectivity and token validity. Returns 200 if the token is valid.

Auth: Bearer <macaroon>

Response

{
  "status": "ok",
  "gateway": "satgate/0.4.0",
  "timestamp": "2026-03-01T12:00:00Z"
}
GET/api/capability/admin

Admin-only endpoint. Requires a token with the api:capability:admin scope. Used for scope enforcement verification.

Auth: Bearer <macaroon> (requires scope = api:capability:admin)

Response

{
  "status": "ok",
  "scope": "api:capability:admin"
}
POST/api/governance/ban

Ban a token by its identifier. Immediately blocks all requests using this token or any delegated children.

Auth: X-Admin-Token

Request Body

{
  "identifier": "agent-001"
}

Response

{
  "banned": true,
  "identifier": "agent-001",
  "cascadeCount": 3
}
GET/api/governance/graph

Return the full delegation tree. Shows parent→child relationships, budget usage, and token status.

Auth: X-Admin-Token

Response

{
  "tree": [
    {
      "id": "root-001",
      "identifier": "research-bot",
      "status": "active",
      "budgetSpent": 30,
      "budgetLimit": 100,
      "children": [
        {
          "id": "child-001",
          "identifier": "sub-agent",
          "status": "active",
          "budgetSpent": 10,
          "budgetLimit": 25,
          "children": []
        }
      ]
    }
  ]
}
POST/api/mint/exchange

Exchange a workload identity token (JWT from an Identity Provider) for a SatGate macaroon. The Mint matches the JWT against configured policies to determine budget, scope, and TTL.

Auth: None (JWT in body)

Request Body

{
  "credentials": "eyJhbGciOiJSUzI1NiIs..."
}

Response

{
  "token": "MDAxY2...",
  "policy": "agent-standard",
  "budget": { "limit": 50, "unit": "credits" },
  "scopes": ["api:*"],
  "expiresAt": "2026-03-01T13:00:00Z"
}