Skip to main content
Most changes between v0 and v1 are the same on every endpoint. This page covers those shared changes once. A resource that changed in its own ways has its own migration guide, and the endpoint map says which endpoints need one.

​
Paths

Every v1 path starts with /v1, and collection names are kebab-case:

​
Custom methods

An action that v0 exposed as a sub-path, or as a DELETE, is a :verb suffix on the resource in v1:
Delete App deletes the app. v0’s DELETE /apps/{app_id} only disconnected it. To disconnect an app in v1, call Disconnect App.
Some HTTP clients and proxies percent-encode a colon in a path. Make sure yours send a literal :.

​
Pagination

v0 paged three different ways. v1 pages one way, on every list: v1 returns no totals. Pagination describes how to tell when you have reached the last page.

​
Errors

Every v1 error has the same body, with the error nested under error: The X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After headers are the same on both versions. v0 and v1 requests count toward one limit for your organization, as Rate limits describes. Branch on error.code instead of on detail or the status alone, as Errors describes.

​
Not found and forbidden

v0 returned 403 for a user or group ID that it couldn’t find. v1 returns 404, as it does for any ID it can’t find, and keeps 403 for a call that you lack permission to make.

​
Identifiers

v1 identifies most resources by a UUID in their id field, as Identifiers describes. A requestable-permission ID that you stored from v0 doesn’t work on v1.

​
Timestamps

v1 returns every timestamp in UTC, as ISO 8601 with a Z suffix, such as 2026-01-15T18:30:00Z. v0 timestamps carried no offset.

​
Status codes

Every v1 endpoint that creates something returns 201. Some of their v0 predecessors returned 200, including POST /apps and POST /access_policies. An app sync, an account upload, an app review sync, and the delete of an app connected through an integration finish in the background. The endpoints that start them return 202 with an operation, which you poll with GET /v1/operations/{operation_id}. Polling the operation replaces v0’s job endpoints. For each operation type, see Long-running operations.

​
Enum values

v1 enum values are lowercase kebab-case labels, such as pending, in-review, or request-validation. They’re the same in responses, filters, path parameters, and request bodies. v0 returned uppercase values, such as APPROVED. A v0 value sent to v1 returns 400, and the error lists the accepted labels. A few fields don’t use labels: activity log event_type and outcome, identity event changed_field, the state in an account upload’s result, error type, a subject filter’s operator and datatype, the group of each scope filter you send to Sync App Review, and a subject’s removal error.code. Each migration guide maps the v0 values for its resource. Users and roles and User offboardings map the values for resources that have no guide.

​
Smaller changes

​
Inline webhooks

GET /v1/inline-webhooks returns a page, {"inline_webhooks": [...], "next_page_token": ...}. v0 returned a bare array. v1 renames the type field from hook_type to type, and changes its values: The Inline Webhook object covers the rest of the object.

​
Users and roles

Wherever v1 returns a user, its status is staged, active, suspended, or inactive. v0 returned STAGED, ACTIVE, and so on. A user’s custom attribute type is text, user, or single-select, where v0 returned TEXT, USER, or SINGLE_SELECT. v0 returned each role in roles and role_added as a name. v1 returns each one as a role object with id, label, is_custom, and resource_type, as Roles describes. v0’s role_name path parameter on Add User Role and Remove User Role is role_id in v1, and it takes the role’s id. A built-in role’s id is its v0 name in kebab case: The path takes the id exactly as written. A v0 role name, such as APP_ADMIN, returns 400 with code set to role.id_required. A custom role’s id is a UUID, which List User Roles returns. The path doesn’t take a custom role’s name.

​
User offboardings

An offboarding’s status is a label on Get User Offboarding and every other call that returns an offboarding:

​
/info and /art

GET /info and GET /art become GET /v1/info and GET /v1/art, with the same response bodies. The v0 pair doesn’t require a token. The v1 pair requires one, so GET /v1/info is a quick check that both your token and your v1 access work.