Skip to navigation
API ReferenceHub AdminProject Users

Add project user

View as Markdown

Assigns a user to the specified project.

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.

Note that if you want to add multiple users at once, you can call POST projects/:projectId/users:import.

Note: This operation is not backward compatible with BIM 360 projects. It only works with Autodesk Construction Cloud projects.

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

Specifies the region where your request should be routed. If not set, the request is routed automatically, which may result in a slight increase in latency.

Possible values: US, EMEA. For a complete list of supported regions, see the Regions page.

User-IdstringOptionalformat: "uuidOrAutodeskId"

The ID of a user on whose behalf your request is acting.

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).

Note that this header is required for hub Admin POST, PATCH, and DELETE endpoints if you want to use a 2-legged authentication context. This header is optional for hub Admin GET endpoints.

Request

User fields to add to the project.
emailstringRequiredformat: "email"<=255 characters
The email address of the user.
companyIdstring or nullOptionalformat: "uuidOrEmptyString"

The ID of the company that the user is representing in the project. To obtain a list of all company IDs associated with a project, call GET projects/:projectId/companies.

companyNamestring or nullOptional<=255 characters
The name of the company to which the user belongs.
roleIdslist of stringsOptional
A list of IDs of the roles that the user belongs to in the project.
productslist of objectsOptional
Information about the products activated in the specified project for this user. Do not include this field if the requester has Member Manager access level.
suppressAutodeskEmailsbooleanOptionalDefaults to false
Suppresses all emails from Autodesk to the invited users. Defaults to false.
suppressAdministrativeEmailsbooleanOptionalDefaults to false
Suppresses project invite emails to the invited users. Defaults to false.

Response headers

RateLimit-Remaininginteger

The number of requests remaining in the current rate-limit window.

RateLimit-Valueinteger
The maximum number of requests that the server is willing to accept during the current full minute
Request-IdstringOptional
A unique ID for the request which can be provided when reporting issues to assist in facilitating improved research.
Response-TimestringOptional
The time taken to generate the response.

Response

Successfully added the user to the project.
emailstringOptionalRead-onlyformat: "email"<=255 characters
The email of the user.
idstringOptionalRead-onlyformat: "uuid"
The Forma ID of the user.
namestringOptionalRead-only<=255 characters
The full name of the user.
firstNamestringOptionalRead-only<=255 characters
The user's first name. This data syncs from the user's Autodesk profile.
lastNamestringOptionalRead-only<=255 characters
The user's last name. This data syncs from the user's Autodesk profile.
autodeskIdstringOptionalRead-only<=255 characters
The ID of the user's Autodesk profile.
analyticsIdstringOptionalRead-only<=255 characters
An ID of the user to be used for analytics.
addressLine1stringOptionalRead-only<=255 characters
The user's address line 1. This data syncs from the user's Autodesk profile.
addressLine2stringOptionalRead-only<=255 characters
The user's address line 2. This data syncs from the user's Autodesk profile.
citystringOptionalRead-only<=255 characters
The User's city. This data syncs from the user's Autodesk profile.
stateOrProvincestring or nullOptionalRead-only<=255 characters
The state or province of the user. The accepted values here change depending on which country is provided. This data syncs from the user's Autodesk profile.
postalCodestringOptionalRead-only<=255 characters
The zip or postal code of the user. This data syncs from the user's Autodesk profile.
countrystring or nullOptionalRead-only<=255 characters
The user's country. This data syncs from the user's Autodesk profile.
imageUrlstringOptionalRead-only<=2048 characters
The URL of the user's avatar. This data syncs from the user's Autodesk profile.
phoneobjectOptionalRead-only
The user's phone number. This data syncs from the user's Autodesk profile.
jobTitlestringOptionalRead-only<=255 characters
The user's job title. This data syncs from the user's Autodesk profile.
industrystringOptionalRead-only<=255 characters
The industry the user works in. This data syncs from the user's Autodesk profile.
aboutMestringOptionalRead-only<=255 characters
A short bio about the user. This data syncs from the user's Autodesk profile.
accessLevelsobjectOptionalRead-only
Flags that identify a returned user's access levels in the hub or project.
addedOndatetimeOptionalRead-only
The timestamp when the user was first given access to any product on the project.
updatedAtdatetimeOptionalRead-only
The timestamp when the project user was last updated, in ISO 8601 format.
companyIdstring or nullOptionalformat: "uuidOrEmptyString"

The ID of the company that the user is representing in the project. To obtain a list of all company IDs associated with a project, call GET projects/:projectId/companies.

companyNamestring or nullOptional<=255 characters
The name of the company to which the user belongs.
companyGroupIdstring or nullOptional<=25 characters
This is the Autodesk identifier of the permissions group to which the company associated to the project user belongs.
roleIdslist of stringsOptional
A list of IDs of the roles that the user belongs to in the project.
roleslist of objectsOptional
A list of the role IDs and names that are associated with the user in the project.
statusstringOptionalRead-only

The status of the user in the project. A pending user could be waiting for their products to activate, or the user hasn’t accepted an email to create a hub with Autodesk.

Possible values:

  • active: The user has been added to the project.
  • pending: The user is in the process of being added to the project.
  • disabled: The user has been temporarily suspended from the project.
  • deleted: The user has been removed from the project.
productslist of objectsOptional
Information about the products activated in the specified project for this user. Do not include this field if the requester has Member Manager access level.
jobIdstringOptionalformat: "uuid"

Not relevant - we don’t currently support this field.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
410
Gone Error
412
Precondition Failed Error
415
Unsupported Media Type Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error