Pagination

Management API list endpoints support two pagination modes, mirroring Auth0:

• Offset pagination — page / per_page (+ optional include_totals). Works everywhere, but pages can shift when rows are inserted mid-walk, and computing totals gets expensive on large tables.
• Checkpoint pagination — from / take with an opaque next cursor. Stable under concurrent writes and cheap at any depth. Preferred for exports and full-table walks.

Offset pagination

GET /api/v2/users?page=0&per_page=50&include_totals=true

• page defaults to 0, per_page to 50.
• Without include_totals=true the response is a bare array; with it you get the Auth0 totals envelope (start, limit, length, total plus the items array).

Checkpoint pagination

GET /api/v2/users?take=50

{
  "users": [ ... ],
  "next": "eyJpIjoiZW1haWx8..."
}

Pass next back verbatim as from to continue:

GET /api/v2/users?take=50&from=eyJpIjoiZW1haWx8...

• take defaults to 50 when omitted.
• next is an opaque cursor — do not parse or construct it. It is absent on the last page, which is the termination signal.
• The response is a plain { <items>, next? } envelope; include_totals is ignored in checkpoint mode — no total is computed.

Supported endpoints

Endpoint	Items field
GET /api/v2/users	users
GET /api/v2/logs	logs
GET /api/v2/clients	clients
GET /api/v2/client-grants	client_grants
GET /api/v2/organizations	organizations
GET /api/v2/organizations/{id}/members	members
GET /api/v2/roles/{id}/users	users
GET /api/v2/connections	connections
GET /api/v2/resource-servers	resource_servers
GET /api/v2/roles	roles
GET /api/v2/roles/{id}/permissions	permissions
GET /api/v2/hooks	hooks
GET /api/v2/actions/actions	actions
GET /api/v2/forms	forms
GET /api/v2/flows	flows
GET /api/v2/grants	grants
GET /api/v2/users/{id}/connected-clients	connected_clients
GET /api/v2/failed-events	events
GET /api/v2/users/{id}/sessions	sessions
GET /api/v2/users/{id}/logs	logs
GET /api/v2/users/{id}/organizations	organizations
GET /api/v2/users/{id}/permissions	permissions
GET /api/v2/users/{id}/roles	roles
GET /api/v2/organizations/{id}/invitations	invitations
GET /api/v2/organizations/{id}/enabled_connections	connections
GET /api/v2/organizations/{id}/members/{user_id}/roles	roles

Other list endpoints accept from/take in their query schema but ignore them and never return next — they stay offset-paginated.

Mode selection and sorting

• Supplying either from or take switches the whole request to checkpoint mode; page and per_page are then ignored.
• Checkpoint walks are ordered by creation time descending (users/logs also accept ascending). On /users only sort=created_at:1|-1 is honored and on /logs only sort=date:1|-1; any other sort column returns 400. /roles/{id}/permissions walks by resource server identifier, then permission name, ascending. /roles and /roles/{id}/permissions return 400 when sort is combined with checkpoint mode; the remaining endpoints use a fixed order and ignore sort.
• /users/{id}/permissions walks by resource server identifier, permission name, then organization id, ascending, and returns 400 when sort or q is combined with checkpoint mode. /users/{id}/roles walks distinct global roles by role id; a role held under several organization scopes is not repeated. /users/{id}/sessions and /users/{id}/organizations walk newest first; /users/{id}/logs follows /logs (date, descending by default).
• /organizations/{id}/invitations walks newest first and ignores sort in checkpoint mode. /organizations/{id}/enabled_connections walks by connection id ascending. /organizations/{id}/members/{user_id}/roles walks distinct roles by role id.
• /hooks, /actions/actions, /forms, /flows and /grants walk newest first with a fixed order (sort is ignored); q and the /grants filters stay in effect.
• /users/{id}/connected-clients walks newest first (soft-deleted clients are dropped, so a page can be shorter than take). /failed-events walks the most recently dead-lettered events first.
• A cursor is bound to the sort it was minted under — replaying it with a different sort returns 400.
• GET /roles/{id}/users caps take (and per_page) at 100, matching Auth0.

Differences from Auth0

• Auth0 does not offer checkpoint pagination on GET /users (offset only, capped at 1000 results); AuthHero does, so full user exports don't need q partitioning tricks.
• Auth0 also pages GET /roles, GET /roles/{id}/permissions and GET /resource-servers by offset only; checkpoint mode on those is an AuthHero extension. GET /connections supports checkpoint in Auth0 too, with the same { connections, next } shape.
• Auth0 documents from as an id; AuthHero keeps it fully opaque so the encoding can evolve.
• Checkpoint walks on /users return primary users only — linked accounts appear as identities on their primary user rather than as separate rows.

Adapter note

The DynamoDB (@authhero/aws) adapter backs checkpoint mode with DynamoDB's own LastEvaluatedKey, so its cursors are not interchangeable with the SQL adapters'. Its last page can carry a next that leads to an empty page, so stop on an empty page as well as on a missing next. GET /roles/{id}/users is not implemented on DynamoDB, and it has no index by role, so that endpoint stays unsupported there. User permissions, user roles and organization connections page within the DynamoDB partition they are stored in: user permissions and roles are partitioned per organization, so /users/{id}/permissions and /users/{id}/roles list the global partition, and /organizations/{id}/members/{user_id}/roles lists that organization's.