API Endpoints

All HTTP endpoints registered by @openape/nuxt-auth-idp and @openape/nuxt-auth-sp.

Authentication

API endpoints use three authentication methods:

IdP — Agent Endpoints

POST /api/agent/enroll

Register a new agent. Requires Management Token or admin session.

curl -X POST https://id.example.com/api/agent/enroll \
  -H "Authorization: Bearer <management-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent+deploy@example.com",
    "name": "deploy-bot",
    "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
  }'

Response: 201 with { agent_id, email, name, owner, approver, status }

POST /api/agent/challenge

Request an authentication challenge. No auth required.

curl -X POST https://id.example.com/api/agent/challenge \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent+deploy@example.com"}'

Response: 200 with { challenge: "<64-char-hex>" }

Challenge expires after 60 seconds. Single-use.

POST /api/agent/authenticate

Authenticate with a signed challenge. No auth required.

curl -X POST https://id.example.com/api/agent/authenticate \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent+deploy@example.com",
    "challenge": "<challenge-from-above>",
    "signature": "<base64-ed25519-signature>"
  }'

Response: 200 with { token, agent_id, email, name, expires_in }

The token is a JWT with claims { sub, act: "agent", iss, iat, exp }.

IdP — Grant Endpoints

POST /api/grants

Create a grant request. Agent token or session optional (auto-sets requester).

curl -X POST https://id.example.com/api/grants \
  -H "Authorization: Bearer <agent-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "requester": "agent+deploy@example.com",
    "target_host": "prod-server.example.com",
    "audience": "escapes",
    "grant_type": "once",
    "command": ["systemctl", "restart", "nginx"],
    "reason": "Deploy hotfix"
  }'

Response: 201 with { id, type, request, status: "pending", created_at }

GET /api/grants

List grants. Session or agent token required.

Query params: status, limit (max 100)

GET /api/grants/:id

Get grant details. Supports ETag-based polling via If-None-Match header.

Response: 200 with full grant object, or 304 Not Modified if unchanged.

POST /api/grants/:id/approve

Approve a pending grant. Requires admin session, management token, or authorized approver.

curl -X POST https://id.example.com/api/grants/<id>/approve \
  -H "Authorization: Bearer <management-token>" \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "timed", "duration": 3600}'

The request body is optional. Use it to override the grant type or duration.

Response: 200 with { grant, authz_jwt }

AuthZ-JWT expiration by grant type:

• once → 5 minutes
• timed → grant.expires_at
• always → 1 hour

POST /api/grants/:id/deny

Deny a pending grant. Same auth as approve.

POST /api/grants/:id/revoke

Revoke an approved grant. Only the agent's approver or admin.

POST /api/grants/:id/token

Get the AuthZ-JWT for an approved grant. Requires agent token or session matching the requester.

Response: 200 with { authz_jwt, grant }

POST /api/grants/:id/consume

Consume a once grant. Requires the AuthZ-JWT as Bearer token.

Response: 200 with { status: "consumed" } for once grants, or { status: "valid" } for timed/always.

POST /api/grants/verify

Verify an AuthZ-JWT. No auth required.

curl -X POST https://id.example.com/api/grants/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "<authz-jwt>"}'

Response: 200 with { valid: true, claims: {...} } or { valid: false, error: "..." }

POST /api/grants/batch

Batch grant operations.

IdP — Delegation Endpoints

POST /api/delegations

Create a delegation. Session or agent token required.

curl -X POST https://id.example.com/api/delegations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "delegate": "agent+bot@example.com",
    "audience": "escapes",
    "scopes": ["read", "exec"],
    "approval": "always"
  }'

GET /api/delegations

List delegations for the current user.

DELETE /api/delegations/:id

Delete a delegation.

POST /api/delegations/:id/validate

Validate a delegation token.

IdP — Admin Endpoints

All admin endpoints require Management Token or admin session.

Users

Agents

Sessions

Registration URLs

IdP — OAuth / OIDC Endpoints

IdP — Auth Endpoints

IdP — Federation Endpoints

SP Endpoints