1. Docs
  2. API Reference
  3. Poll the permission-relevant change feed

Poll the permission-relevant change feed

GET/api/v1/changes

Forward, cursor-paginated catch-up feed of permission- and identity-relevant changes (role assignments, roles, permissions, hierarchy, membership, identity lifecycle, session revocation) — the pull complement to webhooks. Events are returned oldest-first as { id, event, data }, byte-identical to the webhook delivery body so the same handler can process pushed and replayed events. Store pagination.next_cursor and pass it back as ?cursor= to resume; an empty page echoes your cursor so you can keep polling. Account scope comes from the API-key / JWT principal; an env-pinned key only ever sees its own Application/Environment. Replay reaches only as far back as audit rows are retained.

Authentication

Bearer TokenAuthorization Option A

JWT access token

API KeyX-API-Key Option B

API key for management-tier access

Query Parameters

cursorstring Optional

Opaque base64url cursor returned by the previous response as `pagination.next_cursor`. Omit for the first poll.

limitnumber Optional

Page size. Defaults to 50; max 200.

range 1–200

Responses

application/json

  • itemsChangeEventDto[]*
  • paginationobject*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Pagination

This endpoint returns a paginated collection. Use the query parameters below to page through results.

pagenumber

Page number (1-indexed). Defaults to 1.

takenumber

Items per page (1–100). Defaults to 20.

Each response includes an items array alongside a pagination object with item_count, page_count, has_previous_page, and has_next_page fields.

Returned object

ChangeEventDtoView all properties on this resource
Request
curl -X GET "https://auth.canopy-io.com/api/v1/changes?cursor=value&limit=0" \
  -H "X-API-Key: $CANOPY_API_KEY"
Response
{
  "items": [
    {
      "id": "string",
      "event": "string",
      "data": {
        "account_id": "string",
        "application_id": "string",
        "environment_id": "string",
        "actor_id": "string",
        "actor_type": "string",
        "resource_type": "string",
        "resource_id": "string",
        "metadata": {},
        "timestamp": "string"
      }
    }
  ],
  "pagination": {
    "next_cursor": "string"
  }
}
 Related endpoints Was this page helpful?

Tell us how we can improve this guide.

Canopy