Admin REST API

defineConfig({
  // ...
  adminApi: {
    enabled: true,
    apiKeys: [env.get('AUTHKIT_ADMIN_API_KEY')], // one or more high-entropy keys
  },
})

registerAuthHost(router, {
  mountPath: '/oidc',
  adminApi: true, // mirror adminApi.enabled here
})

// Default — API under /api/authkit/v1 (backward-compatible)
registerAuthHost(router, {
  mountPath: '/oidc',
  adminApi: true,
})

// Custom prefix — API under /authkit/api
registerAuthHost(router, {
  mountPath: '/oidc',
  adminApi: { prefix: '/authkit/api' },
})

registerAuthHost(router, {
  mountPath: '/oidc',
  admin: { prefix: '/auth/admin' },
  adminApi: { prefix: '/authkit/api' },
})

import { createAuthkit } from '@adonis-agora/authkit-sdk'

const authkit = await createAuthkit({
  mode: 'remote',
  baseUrl: 'https://auth.acme.com',
  apiKey: process.env.AUTHKIT_ADMIN_API_KEY!,
  apiPrefix: '/authkit/api', // must match adminApi.prefix above
})

Authorization: Bearer <api-key>

{ "error": { "code": "not_found", "message": "..." } }

{
  "meta": { "page": 1, "size": 20, "total": 137 },
  "data": [ /* ... */ ]
}

curl -X POST https://idp.example.com/api/authkit/v1/users \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@example.com", "name": "Jane", "invite": true }'

{
  "id": "acc-42",
  "email": "jane@example.com",
  "name": "Jane",
  "avatarUrl": null,
  "globalRoles": [],
  "disabled": false,
  "invited": true
}

curl -X PATCH https://idp.example.com/api/authkit/v1/users/acc-42 \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "globalRoles": ["ADMIN", "STAFF"] }'

curl https://idp.example.com/api/authkit/v1/users/acc-42/sessions \
  -H "Authorization: Bearer $KEY"

{
  "canList": true,
  "sessions": [{ "id": "sess-…", "accountId": "acc-42", "loginTs": 1700000000, "amr": ["pwd"] }],
  "grants": [{ "id": "grant-…", "accountId": "acc-42", "clientId": "web", "accessTokens": 2, "refreshTokens": 1 }]
}

curl -X POST https://idp.example.com/api/authkit/v1/clients \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "redirectUris": ["https://app.example.com/callback"],
        "grantTypes": ["authorization_code", "refresh_token"],
        "tokenEndpointAuthMethod": "client_secret_basic"
      }'

{ "clientId": "kx9…", "clientSecret": "s3cr3t-shown-once" }

{
  "id": "org-1",
  "name": "Acme",
  "slug": "acme",
  "logoUrl": null,
  "metadata": null,
  "createdAt": "2026-06-05T12:00:00.000Z",
  "memberCount": 4
}

# Create an organization — the owner is added as a member automatically
curl -X POST https://idp.example.com/api/authkit/v1/organizations \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme", "slug": "acme", "ownerAccountId": "acc-42" }'

# Invite somebody into it
curl -X POST https://idp.example.com/api/authkit/v1/organizations/org-1/invitations \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@acme.com", "role": "admin" }'

{
  "id": "inv-9",
  "organizationId": "org-1",
  "email": "jane@acme.com",
  "role": "admin",
  "invitedBy": "admin",
  "expiresAt": "2026-06-12T12:00:00.000Z",
  "acceptedAt": null,
  "createdAt": "2026-06-05T12:00:00.000Z"
}

curl https://idp.example.com/api/authkit/v1/stats \
  -H "Authorization: Bearer $KEY"

{
  "totalUsers": 1024,
  "activeSessions": 87,
  "mau": 312,
  "signInsPerDay": [{ "date": "2026-06-04", "count": 43 }],
  "signUpsPerDay": [{ "date": "2026-06-04", "count": 5 }],
  "signInsTotal": 1290,
  "signUpsTotal": 1024,
  "auditSupported": true,
  "windowDays": 30
}

curl "https://idp.example.com/api/authkit/v1/audit?type=user.created&size=50" \
  -H "Authorization: Bearer $KEY"

{
  "key": "bot_protection",
  "organizationId": null,
  "value": { "enabled": true },
  "updatedAt": "2026-06-05T12:00:00.000Z",
  "updatedBy": null,
  "locked": false
}

{
  "error": {
    "code": "setting_locked",
    "message": "…",
    "details": { "key": "bot_protection", "lockedBy": "config" }
  }
}

# Give one org its own role catalogue and invitation lifetime
curl -X PUT "https://idp.example.com/api/authkit/v1/settings/organizations_policy?organizationId=org-1" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": { "roles": ["owner", "admin", "member", "billing"], "invitationTtlHours": 72 } }'

# Enable bot protection and override the protected flows
curl -X PUT https://idp.example.com/api/authkit/v1/settings/bot_protection \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": { "enabled": true, "on": ["login", "signup", "reset"] } }'

{
  "key": "bot_protection",
  "organizationId": null,
  "value": { "enabled": true, "on": ["login", "signup", "reset"] },
  "updatedAt": "2026-06-05T12:00:00.000Z",
  "updatedBy": null,
  "locked": false
}

# Disable bot protection at runtime
curl -X PUT https://idp.example.com/api/authkit/v1/settings/bot_protection \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": { "enabled": false } }'

# Reset to static config (delete the row)
curl -X DELETE https://idp.example.com/api/authkit/v1/settings/bot_protection \
  -H "Authorization: Bearer $KEY"

{ "key": "bot_protection", "organizationId": null, "deleted": true }

# Close public sign-up at runtime
curl -X PUT https://idp.acme.com/api/authkit/v1/settings/registration \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": { "enabled": false } }'

# Re-open (delete the setting — falls back to config)
curl -X DELETE https://idp.acme.com/api/authkit/v1/settings/registration \
  -H "Authorization: Bearer $KEY"

curl -X PUT https://idp.acme.com/api/authkit/v1/settings/require_verified_email \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": { "enabled": true } }'

# Activate maintenance mode with a custom message
curl -X PUT https://idp.acme.com/api/authkit/v1/settings/maintenance_mode \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": { "enabled": true, "message": "Upgrading — back shortly." } }'

# Lift maintenance (escape hatch — works without a browser session)
curl -X PUT https://idp.acme.com/api/authkit/v1/settings/maintenance_mode \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": { "enabled": false } }'

curl https://idp.example.com/api/authkit/v1/keys \
  -H "Authorization: Bearer $KEY"

{
  "ageDays": 74,
  "policy": { "enabled": true, "maxAgeDays": 90, "keep": 2 },
  "nextRotationInDays": 16,
  "keys": [
    { "kid": "k-2026-03", "alg": "RS256", "ageDays": 74, "active": true },
    { "kid": "k-2025-12", "alg": "RS256", "ageDays": 165, "active": false }
  ]
}

curl -X POST https://idp.example.com/api/authkit/v1/keys/rotate \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keep": 2 }'

{
  "rotated": true,
  "newKid": "k-2026-06",
  "retiredKids": [],
  "keptKids": ["k-2026-06", "k-2026-03"]
}

import { buildKeysStatus, rotateNow } from '@adonis-agora/authkit-server'
import type { ServerKeysStatus } from '@adonis-agora/authkit-server'

// Reads age + effective policy + ETA. `null` means the JWKS is not a managed
// keystore — the REST layer translates that to 501.
const status: ServerKeysStatus | null = await buildKeysStatus(service, settings)

// Validates `keep`/`retire` and performs the rotation, auditing as it goes.
const result = await rotateNow(service, { keep: 2, retire: false })
// { rotated: true, newKid, retiredKids, keptKids }

curl -X POST https://idp.example.com/api/authkit/v1/tokens/verify \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "token": "pat_…" }'

{
  "active": true,
  "tokenType": "pat",
  "sub": "acc-42",
  "email": "jane@example.com",
  "name": "Jane",
  "roles": ["ADMIN"],
  "scopes": ["read"],
  "audience": null,
  "exp": null
}