Grant Subject Token

Issue a project-scoped token for one business subject.

POST /v1/subject/grants

Authentication

Use a project-bound tenant API key with subject_jwt:grant. Service credentials and keys without a project are rejected. Keep this key on your backend.

Authorization: Bearer <tenant-api-key>
Content-Type: application/json

Request Body

Field	Contract
`subject_type`	Required non-blank string, for example `user`, `organization`, `agent`.
`subject_id`	Required non-blank business subject ID. Resolve from your authenticated session.
`rules`	Required non-empty array. Currently only `analysis` is supported; duplicates are removed.
`metrics`	Optional exact metric-name allowlist. Omitted or `null` permits all metrics for this subject; `[]` is invalid. Up to 100 distinct names, each at most 256 bytes, no whitespace; names are trimmed, deduplicated and sorted.
`expires_in`	Optional integer seconds. Positive values request a lifetime up to the configured maximum. Omitted, zero or negative uses the configured default. Defaults: 900 seconds, maximum 3600 seconds; operators can change both.

Tenant and project are inherited from the API key; do not send them in the body. Unknown JSON fields are rejected. Granting a token does not create a subject route or wallet. analysis also permits realtime balance reads: the metric allowlist restricts usage data, not wallet balances. Renew by requesting a new token from your backend.

Example

curl 'http://127.0.0.1:8080/v1/subject/grants' \
  -H 'Authorization: Bearer <tenant-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{"subject_type": "user", "subject_id": "user_123", "rules": ["analysis"], "metrics": ["input_tokens"], "expires_in": 900}'

Response

200 OK

{
  "token_type": "Bearer",
  "access_token": "<subject-token>",
  "expires_in": 900,
  "expires_at": 1781223300,
  "subject": {
    "type": "user",
    "id": "user_123"
  },
  "rules": [
    "analysis"
  ],
  "metrics": [
    "input_tokens"
  ]
}

Field	Contract
`token_type`	Always `Bearer`.
`access_token`	Signed short-lived JWT.
`expires_in`	Actual lifetime in seconds.
`expires_at`	Expiry as Unix seconds.
`subject`	Object with `type` and `id`.
`rules`	Granted rules.
`metrics`	Optional normalized metric allowlist; omitted for unrestricted metrics.

Errors

Errors use {"error":"message"}.

400: invalid request fields or token lifetime; 401: missing or invalid API key; 403: insufficient grant permission, service credentials, or missing project binding. 503: authentication dependencies are unavailable or the Subject Token signing service is not configured. Messages are public English strings; internal causes are retained only in server logs.

{"error":"subject token service unavailable"}