Skip to navigation
API ReferenceHub AdminProject Roles

Sync project roles

View as Markdown

Retrieves project roles for a mobile client, implementing the Mobile Sync 1.1 standard.

A sync begins with an empty cursorState. Each response returns a pagination.nextPost containing the exact URL and body for the following request, so the client replays it until pagination.moreData is false. Keep the final cursorState: passing it later returns only what changed since.

Use fields: ["id", "hash"] to retrieve fingerprints alone, compare them against what the device already holds, and then re-request only the roles that differ using filters.id.

current.data and deleted.data are keyed by collection — this endpoint returns only roles — so that a response can carry several collections in future without a breaking change.

This endpoint supersedes /construction/admin/v1/projects/{projectId}/roles:sync, which remains available and unchanged. Sync status is not duplicated here — continue to use /construction/admin/v1/projects/{projectId}/roles:sync-status, passing the cursorState as its syncToken.

Note that the Authorization header token can be obtained either via a three-legged OAuth flow, or via a two-legged Oauth flow with user impersonation, for which the User-Id header is required.

Authentication

AuthorizationBearer

OAuth 2.0 (2-legged with impersonation) — application context with user impersonation required. Send a User-Id header identifying the member to act on behalf of; the token authorizes the application, while the operation is evaluated against that member’s project permissions.

Client Credentials Flow

Token URL: https://developer.api.autodesk.com/authentication/v2/token

Scopes:

  • account:read — read account and project data
  • account:write — modify account and project data
OR
AuthorizationBearer

OAuth 2.0 (3-legged) — user context required. Also accepts a Secure Service Account (SSA) token, which is headless like a two-legged flow but classified as three-legged because it preserves user context.

Authorization Code Flow

Authorization URL: https://developer.api.autodesk.com/authentication/v2/authorize

Token URL: https://developer.api.autodesk.com/authentication/v2/token

Refresh URL: https://developer.api.autodesk.com/authentication/v2/token

Scopes:

  • data:read — read your data
  • account:read — read account and project data
  • account:write — modify account and project data

Path parameters

projectIdstringRequiredformat: "uuid"

The ID of the project. This corresponds to project ID in the Data Management API. To convert a project ID in the Data Management API into a project ID in the Forma API you need to remove the “b.” prefix. For example, a project ID of b.a4be0c34a-4ab7 translates to a project ID of a4be0c34a-4ab7.

Headers

Accept-LanguagestringOptionalDefaults to en
This header is not currently supported in the Hub Admin API.
RegionstringOptional

The region that the data is stored in. For a full list of supported regions, please check here.

User-IdstringOptionalformat: "uuidOrAutodeskId"

Note that this header is not relevant for Hub Admin GET endpoints.

The ID of a user on whose behalf your API request is acting. Required if you’re using a 2-legged authentication context, which must be 2-legged OAuth2 security with user impersonation.

Your app has access to all users specified by the administrator in the SaaS integrations UI. Provide this header value to identify the user to be affected by the request.

You can use either the user’s Forma ID (id), or their Autodesk ID (autodeskId).

Request

The Mobile Sync 1.1 request body. Optional; an empty body starts a full sync of every role in the project.

filtersobjectOptional

Restricts the sync. Omit or send an empty object to sync every role in the project.

Send array values in a consistent order between requests. The cursor records the filters a sync began with, and the comparison that detects a filter change is order-sensitive for array values, so re-sending the same ids in a different order reads as a new filter: the response carries overwrite: true and the client re-downloads the collection from the start. The order of keys within filters does not matter, only the order of values inside an array.

Replaying pagination.nextPost.body verbatim avoids this, since the server echoes the filters back in the order it recorded them.

fieldslist of stringsOptional

The fields to return on each item. Omit it or send an empty array for the full role.

id and hash are valid values alongside the role’s other fields, so ["id", "hash"] returns fingerprints only. id is always present regardless.

cursorStatestringOptional

Opaque pagination and watermark token from the previous response’s pagination.nextPost.body.cursorState. Empty or absent starts a fresh sync.

Changing filters while presenting a cursor restarts the sync, and the response carries pagination.overwrite: true.

Changing fields does not. The cursor records the filters only, so a client can fetch ["id", "hash"], compare the fingerprints against what it holds, and then re-request the entities that differ under the same cursor without restarting.

limitintegerOptional>=1000

Requested maximum entities per page. Defaults to the server maximum.

The floor of 1000 is the Mobile Sync standard’s minimum request size. This endpoint serves up to 10000 per page, matching the largest data array the standard’s response schema allows, so any value in 1000..10000 is honoured and anything larger is reduced to 10000.

Response

The project roles to be synced (added/removed) on the device.

currentobject
deletedobject
paginationobject
Pagination and watermark state for the sync.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
406
Not Acceptable Error
410
Gone Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error