Netlify Identity Admin API user listing pagination configuration

Implementation

To paginate through all users of a Netlify site using the Identity Admin API, use the per_page and page query parameters. Because the API does not provide a total count or a pagination header, you must implement a while loop that continues until an empty array is returned.

Request Configuration

The endpoint follows this structure:

GET /api/v1/sites/:site_id/users?per_page=100&page=1

1. Set per_page: Use a value of 100. While not explicitly documented as the hard limit, empirical evidence suggests the API silently caps requests at this value; requesting more may result in truncation or a default fallback.
2. Iterate page: Start at page=1 and increment by one for each subsequent request.
3. Termination Condition: Stop the loop when the API returns an empty array [] with an HTTP 200 status.

Reliability and Constraints

The following behaviors are observed in the Identity Admin API and should be handled in your client logic:

• End-of-Dataset Detection: There is no X-Total-Pages or Link header. The only reliable way to detect the end of the user list is to verify if the returned JSON array length is zero.
• Authentication: Ensure your request includes a Bearer token with full administrative privileges. A token with limited identity scope may result in a 403 Forbidden error when accessing the Admin API endpoints.
• Rate Limiting: When paginating through large datasets, implement a small delay between requests to avoid triggering Netlify's API rate limits.

Verification Command

You can verify the pagination behavior using curl. Replace <TOKEN> and <SITE_ID> with your actual credentials:

curl -H "Authorization: Bearer <TOKEN>" "https://api.netlify.com/api/v1/sites/<SITE_ID>/users?per_page=10&page=1"

Compare the result of page=1 with page=2 to ensure the user set shifts as expected.

Diagnostic Note: If you are receiving a 403 Forbidden error despite having a token, please clarify if the token was generated as a Personal Access Token or via a specific OAuth scope, as this changes the permission level.