Administrative REST API endpoints for tenant-level management, impersonation, and bulk operations.

Admin API

The Admin API provides elevated operations for tenant administrators and backend services. All endpoints require a secret key (sk_live_...).

GET /v1/admin/stats

Get aggregate statistics for the entire tenant.

curl "https://api.hellojohn.dev/v1/admin/stats" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Response:

{
  "users": {
    "total": 1842,
    "active_last_7d": 324,
    "active_last_30d": 891,
    "new_last_7d": 47,
    "new_last_30d": 183
  },
  "sessions": {
    "active": 412,
    "created_last_24h": 98
  },
  "mfa": {
    "enrolled_users": 623,
    "enrollment_rate": 0.34
  },
  "organizations": {
    "total": 87,
    "active_last_30d": 54
  },
  "auth": {
    "sign_ins_last_24h": 156,
    "failed_sign_ins_last_24h": 12
  }
}

POST /v1/admin/users/search

Advanced user search with filtering and sorting. More powerful than GET /v1/users?q=....

Body:

Field	Type	Description
`query`	string	Search across email, name, phone
`filters`	object	Filter conditions
`sort`	object	Sort field and direction
`limit`	integer	Default `20`, max `100`
`cursor`	string	Pagination cursor

curl -X POST "https://api.hellojohn.dev/v1/admin/users/search" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "alice",
    "filters": {
      "created_after": "2024-01-01T00:00:00Z",
      "mfa_enrolled": true,
      "organization_id": "org_01HABCDEF777666"
    },
    "sort": {
      "field": "created_at",
      "direction": "desc"
    },
    "limit": 50
  }'

Filter options:

Filter	Type	Description
`created_after`	ISO date	Users created after this date
`created_before`	ISO date	Users created before this date
`last_active_after`	ISO date	Last active after this date
`mfa_enrolled`	boolean	Has at least one MFA factor
`email_verified`	boolean	Email is verified
`disabled`	boolean	Account is disabled
`organization_id`	string	Member of this organization
`role`	string	Has this system role

POST /v1/admin/users/impersonate

Get an access token for a user without their credentials. Useful for support and debugging.

Body:

Field	Type	Required	Description
`user_id`	string	✅	User to impersonate
`reason`	string	—	Audit log reason
`expires_in`	string	—	Token lifetime (default: `1h`)

curl -X POST "https://api.hellojohn.dev/v1/admin/users/impersonate" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_01HABCDEF123456",
    "reason": "Support ticket #1234"
  }'

Response: 200 OK

{
  "access_token": "eyJhbGciOiJFZERTQSJ9...",
  "user_id": "usr_01HABCDEF123456",
  "expires_in": 3600,
  "impersonated_by": "support@example.com",
  "audit_id": "aud_01HABCDEF000111"
}

All impersonation events are recorded in the audit log with the actor.impersonated_by field.

POST /v1/admin/sessions/revoke-all

Revoke all active sessions for the tenant. Use with caution — this signs out all users.

Body:

Field	Type	Description
`reason`	string	Audit log reason
`exclude_user_id`	string	Keep sessions for this user (e.g., your own admin account)

curl -X POST "https://api.hellojohn.dev/v1/admin/sessions/revoke-all" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Security incident response",
    "exclude_user_id": "usr_01HABCDEF999999"
  }'

Response: 200 OK

{ "revoked": 412 }

POST /v1/admin/users/bulk-disable

Disable multiple users in a single request.

Body:

Field	Type	Required	Description
`user_ids`	array	✅	List of user IDs (max 100)
`reason`	string	—	Audit log reason
`revoke_sessions`	boolean	—	Also revoke sessions (default: `true`)

curl -X POST "https://api.hellojohn.dev/v1/admin/users/bulk-disable" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["usr_01HABCDEF123456", "usr_01HABCDEF789012"],
    "reason": "Compliance review"
  }'

Response: 200 OK

{
  "disabled": 2,
  "sessions_revoked": 7
}

GET /v1/admin/audit-logs

Query the tenant audit log. See Audit Logs API for details.

Query parameters:

Parameter	Type	Description
`actor_id`	string	Filter by actor (user who performed action)
`action`	string	Filter by action type
`resource_type`	string	`user`, `session`, `organization`, `api_key`
`from`	ISO date	Start of time range
`to`	ISO date	End of time range
`limit`	integer	Default `50`, max `500`
`cursor`	string	Pagination cursor

curl "https://api.hellojohn.dev/v1/admin/audit-logs?action=user.deleted&from=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Response:

{
  "data": [
    {
      "id": "aud_01HABCDEF000111",
      "action": "user.deleted",
      "actor": {
        "id": "usr_01HABCDEF999999",
        "email": "admin@example.com",
        "type": "user"
      },
      "resource": {
        "type": "user",
        "id": "usr_01HABCDEF123456"
      },
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0...",
      "created_at": "2024-01-20T08:15:00Z"
    }
  ],
  "next_cursor": "cur_..."
}

GET /v1/admin/config

Get the current tenant authentication configuration.

PATCH /v1/admin/config

Update the tenant authentication configuration. See Tenants API — Auth Config Options for available fields.

curl -X PATCH "https://api.hellojohn.dev/v1/admin/config" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "mfa_required": true,
    "session_duration": "14d",
    "password_min_length": 12
  }'

Response: 200 OK — Returns updated config object.

Admin API

On this page