Migrate to Management API v2 Endpoint Paginated Queries

After 26 January 2021 (or Private Cloud version 2202), requests to Management API v2 endpoints will return a maximum of 50 items for tenants in the Public Cloud. To retrieve more items, you must include the page and per_page parameters. Beginning on 21 July 2020 (or Private Cloud version 2108), Auth0 will display tenant logs and a migration toggle to help you prepare for this change.

Affected tenants are those that meet the following criteria:

• Public Cloud tenants created before 21 July 2020 or Private Cloud deployments on version 2108
• Actively making calls to the affected endpoints without passing the per_page parameter for queries that can return more than 1 result.

The following tenants will default to the new pagination behavior and will continue to operate as they do today after 26 January 2021:

• Public Cloud tenants created on or after 21 July 2020 or Private Cloud deployments on version 2108 or higher
• Not using any of the affected endpoints
• Using the affected endpoints and passing the per_page parameter, or making queries that will always return a single result.

Endpoints affected

Calls to the following Management API v2 endpoints are affected:

• GET /api/v2/clients
• GET /api/v2/client_grants
• GET /api/v2/grants
• GET /api/v2/connections
• GET /api/v2/device-credentials
• GET /api/v2/resource-servers
• GET /api/v2/rules

Deprecation notices will be recorded in your tenant logs for all requests without pagination options that are currently returning more than 1 item, once per hour, for each different client and endpoint.

Actions

1. Replace all calls to the affected endpoints by providing the page and per_page parameters.

Parameter	Type	Description
page	Integer	Page index of the results to return. First page is 0.
per_page	Integer	Number of results per page. Paging is disabled if the parameter is not sent.

2. Confirm that you are no longer seeing deprecation notices in your tenant logs. Check if a request returned more than 50 items. Look at the details.size_exceeded field and check if it’s true.

   1. Use the following log query to return all calls without pagination options with more than 1 result: type:depnote AND description:*Unpaginated*
   2. Use the following log query to return all calls without pagination options with more than 50 results: type:depnote AND description:*Unpaginated* AND details.size_exceeded:true

   To identify the application making the request, logs will include the client_id used to make the request. You can also find the endpoint being used in the logs details.path field.

3. Disable Management API unpaginated requests for your tenant. Go to Dashboard > Tenant Settings > Advanced > Migration. This will simulate the expected behavior after the migration window closes, causing calls to affected endpoints to return up to 50 results. You will be able to re-enable unpaginated requests any time before that date.

Update extensions

You may need to update from previous versions of Auth0 Extensions and custom extensions to the latest versions to make sure they are only performing paginated queries.

1. Check your tenant logs for deprecation notices for clients with an ID matching an extension URL. It means you will need to update that extension.
2. Go to Dashboard > Extensions, select Installed Extensions, and click on the extension’s Update link if present.

Update Deploy CLI tool

If you are using the auth0-deploy-cli tool, you must update to version 5.3.0 or later. To learn more, see Deploy CLI Tool.