Please ensure Javascript is enabled for purposes of website accessibility
Powered by Zoomin Software. For more details please contactZoomin

CONNECT data services developer documentation

TABLE OF CONTENTS

Tenants Users

Save PDF
Save selected topicSave selected topic and subtopicsSave all topics
Share
Share to emailCopy topic URL
  • Last UpdatedSep 08, 2023
  • 10 minute read

Users consume resources in a tenant. They are invited by the administrator of the tenant and should already have a tenant in one of the configured identity providers for this tenant. A user is fully provisioned in the platform only after they have accepted the invitation and successfully logged in with an identity provider. The platform does not maintain user credentials, but it delegates authentication to the identity provider the user logged in with at first. Once logged in, the user cannot change the identity provider with which it signed up. A tenant can only have one user with a given email to an identity provider. If a user has multiple aliases in the same identity provider, they will not be able to create multiple corresponding users in the platform. Users have roles associated with them. These roles determine what a user is authorized to do in the tenant. Roles are assigned to a user upon creation and can be modified by an administrator. We allow the change of some user fields and the complete deletion of a user.

List Users from a Tenant

Returns a list of users from a tenant. Optionally, returns a list of requested users. Total number of users in the tenant set in the Total-Count header.

Request

GET /api/v1/Tenants/{tenantId}/Users
?id={id}&query={query}&skip={skip}&count={count}

Parameters

string tenantId
Tenant identifier.

[optional] array id
Unordered list of identifiers of all users to return

[optional] string query
(Not supported) Search string identifier.

[optional] integer skip
Parameter representing the zero-based offset of the first object to retrieve. If unspecified, a default value of 0 is used.

[optional] integer count
Parameter representing the maximum number of objects to retrieve. If unspecified, a default value of 100 is used.

Response

Status Code Body Type Description
200 User[] List of users found
207 UserMultiStatusResponse List of users found
400 ErrorResponse Missing or invalid inputs.
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse Tenant not found
500 ErrorResponse Internal server error.

Example response body

200 Response (User[])

[
  {
    "Id": "string",
    "GivenName": "string",
    "Surname": "string",
    "Name": "string",
    "Email": "user@example.com",
    "ContactEmail": "user@example.com",
    "ContactGivenName": "string",
    "ContactSurname": "string",
    "ExternalUserId": "string",
    "IdentityProviderId": "string",
    "RoleIds": [
      "string"
    ]
  }
]

Authorization

Allowed for these roles:

  • Tenant Member

Get Total Count of Users

Returns the total number of users in a tenant. Optionally, check based on a list of requested users. The value will be set in the Total-Count header. This method is identical to the GET method, but it does not return any objects in the body.

Request

HEAD /api/v1/Tenants/{tenantId}/Users
?id={id}

Parameters

string tenantId
Tenant identifier.

[optional] array id
Unordered list of user identifiers

Response

Status Code Body Type Description
200 None User header found
401 None Unauthorized.
403 None Forbidden.
404 None User not found
500 None Internal server error.

Authorization

Allowed for these roles:

  • Tenant Member

Create User

Creates a user in the tenant. This method does not create an invitation for the user. You will need to create an invitation with the respective method for this user, otherwise they will not be able to finish the sign-up process. Users have identifiers in a tenant. Currently there is a limit of 50000 users per tenant.

Request

POST /api/v1/Tenants/{tenantId}/Users

Parameters

string tenantId
Tenant identifier.

Request Body

UserCreateOrUpdate object

{
  "Id": "string",
  "ExternalUserId": "string",
  "ContactGivenName": "string",
  "ContactSurname": "string",
  "ContactEmail": "user@example.com",
  "IdentityProviderId": "string",
  "IdentityProviderSpecificUserId": "string",
  "RoleIds": [
    "string"
  ]
}

Response

Status Code Body Type Description
201 User User created
400 ErrorResponse Missing or invalid inputs, or the user limit exceeded for tenant.
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse Tenant not found
408 ErrorResponse Operation timed out.
500 ErrorResponse Internal server error.

Example response body

201 Response (User)

{
  "Id": "string",
  "GivenName": "string",
  "Surname": "string",
  "Name": "string",
  "Email": "user@example.com",
  "ContactEmail": "user@example.com",
  "ContactGivenName": "string",
  "ContactSurname": "string",
  "ExternalUserId": "string",
  "IdentityProviderId": "string",
  "RoleIds": [
    "string"
  ]
}

Authorization

Allowed for these roles:

  • Tenant Administrator

List Users' Invitation Status

Returns the status of the invitations for multiple users. Optionally, restrict it only to users of a specific invitation status. The user status can be: InvitationAccepted (0), NoInvitation (1), InvitationNotSent (2), InvitationSent (3), InvitationExpired (4).

Request

GET /api/v1/Tenants/{tenantId}/Users/Status
?id={id}&query={query}&skip={skip}&count={count}&status={status}

Parameters

string tenantId
Tenant identifier.

[optional] array id
Unordered list of identifiers of all users to return

[optional] string query
(Not supported) Search string identifier.

[optional] integer skip
Parameter representing the zero-based offset of the first object to retrieve. If unspecified, a default value of 0 is used.

[optional] integer count
Parameter representing the maximum number of objects to retrieve. If unspecified, a default value of 100 is used.

[optional] array status
Only return statuses that match these values. Possible user statuses are: InvitationAccepted, NoInvitation, InvitationNotSent, InvitationSent, InvitationExpired.

Response

Status Code Body Type Description
200 UserStatus[] List of user statuses found
400 ErrorResponse Missing or invalid inputs.
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse Tenant not found
500 ErrorResponse Internal server error.

Example response body

200 Response (UserStatus[])

[
  {
    "InvitationStatus": 0,
    "User": {
      "Id": "string",
      "GivenName": "string",
      "Surname": "string",
      "Name": "string",
      "Email": "user@example.com",
      "ContactEmail": "user@example.com",
      "ContactGivenName": "string",
      "ContactSurname": "string",
      "ExternalUserId": "string",
      "IdentityProviderId": "string",
      "RoleIds": [
        "string"
      ]
    }
  }
]

Authorization

Allowed for these roles:

  • Tenant Member

Get User from a Tenant

Returns a specific user from a tenant.

Request

GET /api/v1/Tenants/{tenantId}/Users/{userId}

Parameters

string tenantId
Tenant identifier.

string userId
User identifier.

Response

Status Code Body Type Description
200 User User specified
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse User or tenant not found
500 ErrorResponse Internal server error.

Example response body

200 Response (User)

{
  "Id": "string",
  "GivenName": "string",
  "Surname": "string",
  "Name": "string",
  "Email": "user@example.com",
  "ContactEmail": "user@example.com",
  "ContactGivenName": "string",
  "ContactSurname": "string",
  "ExternalUserId": "string",
  "IdentityProviderId": "string",
  "RoleIds": [
    "string"
  ]
}

Authorization

Allowed for these roles:

  • Self
  • Tenant Member

Get Header for User

Validates that a user exists. This method is identical to the GET method, but it does not return an object in the body.

Request

HEAD /api/v1/Tenants/{tenantId}/Users/{userId}

Parameters

string tenantId
Tenant identifier.

string userId
User identifier.

Response

Status Code Body Type Description
200 None Header for user
401 None Unauthorized.
403 None Forbidden.
404 None User does not exist
500 None Internal server error.

Authorization

Allowed for these roles:

  • Self
  • Tenant Member

Update User in a Tenant

Updates a user in a tenant. The user identifier cannot be changed.

Request

PUT /api/v1/Tenants/{tenantId}/Users/{userId}

Parameters

string tenantId
Tenant identifier.

string userId
User identifier.

Request Body

UserCreateOrUpdate object. Properties that are not set or are null will not be changed.

{
  "Id": "string",
  "ExternalUserId": "string",
  "ContactGivenName": "string",
  "ContactSurname": "string",
  "ContactEmail": "user@example.com",
  "IdentityProviderId": "string",
  "IdentityProviderSpecificUserId": "string",
  "RoleIds": [
    "string"
  ]
}

Response

Status Code Body Type Description
200 User Updated user
400 ErrorResponse Missing or invalid inputs.
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse User or tenant not found
408 ErrorResponse Operation timed out.
500 ErrorResponse Internal server error.

Example response body

200 Response (User)

{
  "Id": "string",
  "GivenName": "string",
  "Surname": "string",
  "Name": "string",
  "Email": "user@example.com",
  "ContactEmail": "user@example.com",
  "ContactGivenName": "string",
  "ContactSurname": "string",
  "ExternalUserId": "string",
  "IdentityProviderId": "string",
  "RoleIds": [
    "string"
  ]
}

Authorization

Allowed for these roles:

  • Tenant Administrator

Delete User in a Tenant

Deletes a user. Users cannot delete themselves. Deleting a user does not invalidate any of the existing access tokens, but it prevents this user from being able to authenticate in the future. Existing access tokens for the user will be valid until their expiration date. Refresh tokens on behalf of the user will no longer be valid after the user has been deleted. Deleting a user with explicit and claim role mappings will only have their explicit roles deleted. Forcibly deleting a user will delete a user completely regardless of claim role mappings.

Request

DELETE /api/v1/Tenants/{tenantId}/Users/{userId}
?force={force}

Parameters

string tenantId
Tenant identifier.

string userId
User identifier.

[optional] boolean force
Forcibly delete a user that can remain due to claim role mappings.

Response

Status Code Body Type Description
200 string No content
204 None No content
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse User or tenant not found
408 ErrorResponse Operation timed out.
500 ErrorResponse Internal server error.

Authorization

Allowed for these roles:

  • Tenant Administrator

Get User's Invitation Status

Returns invitation status for a user. It can be: InvitationAccepted (0), NoInvitation (1), InvitationNotSent (2), InvitationSent (3), InvitationExpired (4).

Request

GET /api/v1/Tenants/{tenantId}/Users/{userId}/Status

Parameters

string tenantId
Tenant identifier.

string userId
User identifier.

Response

Status Code Body Type Description
200 UserStatus User status for user specified
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse User or tenant not found
500 ErrorResponse Internal server error.

Example response body

200 Response (UserStatus)

{
  "InvitationStatus": 0,
  "User": {
    "Id": "string",
    "GivenName": "string",
    "Surname": "string",
    "Name": "string",
    "Email": "user@example.com",
    "ContactEmail": "user@example.com",
    "ContactGivenName": "string",
    "ContactSurname": "string",
    "ExternalUserId": "string",
    "IdentityProviderId": "string",
    "RoleIds": [
      "string"
    ]
  }
}

Authorization

Allowed for these roles:

  • Self
  • Tenant Member

Get User's Preferences

Returns preferences from a user. User preferences can be any valid JSON object. A common use case is to store UI preferences for the user.

Request

GET /api/v1/Tenants/{tenantId}/Users/{userId}/Preferences

Parameters

string tenantId
Tenant identifier.

string userId
User identifier.

Response

Status Code Body Type Description
200 Inline User preferences for specified user
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse User or tenant not found
422 ErrorResponse Unprocessable entity

Authorization

Allowed for these roles:

  • Self

Get Header for User's Preferences

Validates that there are preferences for a user. This method is identical to the GET method, but it does not return any objects in the body.

Request

HEAD /api/v1/Tenants/{tenantId}/Users/{userId}/Preferences

Parameters

string tenantId
Tenant identifier.

string userId
User identifier.

Response

Status Code Body Type Description
200 None Header for specified user's preferences
401 None Unauthorized.
403 None Forbidden.
404 None User or tenant or user's preferences not found.
500 None Internal server error.

Authorization

Allowed for these roles:

  • Self

Update User's Preferences

Updates preferences for a user.

Request

PUT /api/v1/Tenants/{tenantId}/Users/{userId}/Preferences

Parameters

string tenantId
Tenant identifier.

string userId
User identifier.

Response

Status Code Body Type Description
200 Inline Updated user preferences
400 ErrorResponse Missing or invalid inputs.
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse User or tenant not found
408 ErrorResponse Operation timed out.

Authorization

Allowed for these roles:

  • Self

Definitions

User

Object for retrieving a user

Properties

Property Name Data Type Required Nullable Description
Id guid false false User identifier
GivenName string false true Given name of the user
Surname string false true Surname of the user
Name string false true Name of the user
Email email false true Email of the user
ContactEmail email false true Contact email for the user. User will only be contacted through this email.
ContactGivenName string false true Preferred given name for the user
ContactSurname string false true Preferred contact surname for the user
ExternalUserId string false true Provider identifier for the user. This is the identifier we get from the identity provider.
IdentityProviderId guid false true Identity provider identifier used to authenticate the user. This cannot be set to null, and must be set when creating a new user.
RoleIds string[] false true List of roles to be assigned to this client. Member role is always required. For security reasons we advise against assigning administrator role to a client. 
{
  "Id": "string",
  "GivenName": "string",
  "Surname": "string",
  "Name": "string",
  "Email": "user@example.com",
  "ContactEmail": "user@example.com",
  "ContactGivenName": "string",
  "ContactSurname": "string",
  "ExternalUserId": "string",
  "IdentityProviderId": "string",
  "RoleIds": [
    "string"
  ]
}

UserMultiStatusResponse

MultiStatusResponse objects returned in a 207 response

Properties

Property Name Data Type Required Nullable Description
OperationId string false true Identifier of the operation that resulted in this error
Error string false true Message describing the error
Reason string false true Reason that caused the error
EventId string false true Event identifier of the error
ChildErrors [MultiStatusResponseChildError] false true List of child errors
Data [User] false true Data representing users 
{
  "OperationId": "string",
  "Error": "string",
  "Reason": "string",
  "EventId": "string",
  "ChildErrors": [
    {
      "OperationId": "string",
      "Error": "string",
      "Reason": "string",
      "Resolution": "string",
      "EventId": "string",
      "StatusCode": 0,
      "ModelId": "string",
      "property1": null,
      "property2": null
    }
  ],
  "Data": [
    {
      "Id": "string",
      "GivenName": "string",
      "Surname": "string",
      "Name": "string",
      "Email": "user@example.com",
      "ContactEmail": "user@example.com",
      "ContactGivenName": "string",
      "ContactSurname": "string",
      "ExternalUserId": "string",
      "IdentityProviderId": "string",
      "RoleIds": [
        "string"
      ]
    }
  ]
}

MultiStatusResponseChildError

ChildError objects returned in a 207 response

Properties

Property Name Data Type Required Nullable Description
OperationId string true false OperationId of action that caused the error
Error string true false Error description
Reason string true false Reason for the error
Resolution string true false Resolution for the error
EventId string true false EventId for the error
StatusCode int32 false false Http status code
ModelId string false true Model identifier 
{
  "OperationId": "string",
  "Error": "string",
  "Reason": "string",
  "Resolution": "string",
  "EventId": "string",
  "StatusCode": 0,
  "ModelId": "string",
  "property1": null,
  "property2": null
}

ErrorResponse

Object returned whenever there is an error

Properties

Property Name Data Type Required Nullable Description
OperationId string true false Operation identifier of action that caused the error
Error string true false Error description
Reason string true false Reason for the error
Resolution string true false Resolution to resolve the error
DynamicProperties object false true Additional properties 
{
  "OperationId": "string",
  "Error": "string",
  "Reason": "string",
  "Resolution": "string",
  "DynamicProperties": {
    "property1": null,
    "property2": null
  },
  "property1": null,
  "property2": null
}

UserStatus

Object used when returning user status

Properties

Property Name Data Type Required Nullable Description
InvitationStatus UserInvitationStatus false false Status of user invitation. Can be: InvitationAccepted (0), NoInvitation (1), InvitationNotSent (2), InvitationSent (3), InvitationExpired (4).
User User false true User information 
{
  "InvitationStatus": 0,
  "User": {
    "Id": "string",
    "GivenName": "string",
    "Surname": "string",
    "Name": "string",
    "Email": "user@example.com",
    "ContactEmail": "user@example.com",
    "ContactGivenName": "string",
    "ContactSurname": "string",
    "ExternalUserId": "string",
    "IdentityProviderId": "string",
    "RoleIds": [
      "string"
    ]
  }
}

UserInvitationStatus

User Invitation Status

Enumerated Values

Property Value
InvitationAccepted 0
NoInvitation 1
InvitationNotSent 2
InvitationSent 3
InvitationExpired 4

UserCreateOrUpdate

Object when updating a user

Properties

Property Name Data Type Required Nullable Description
Id guid false true User identifier. When creating a user, if user identifier is not specified, one will be generated.
ExternalUserId string false true User ExternalUserId for the user. Must be specified if the identity provider is Windows Active Directory.
ContactGivenName string false true Preferred name to be used when contacting user
ContactSurname string false true Preferred surname to be used when contacting user
ContactEmail email false true Preferred contact email to be used. This does not have to be the same as the user's identity provider email.
IdentityProviderId guid false true Identity provider this user will be required to use to log in. This value cannot be null when creating a new user. When updating, this value must match what is currently assigned to user. This cannot be updated via update user.
IdentityProviderSpecificUserId string false true Identity provider specific user identifier. For example, object Id for Active Directory and Azure Active Directory.
RoleIds string[] false true List of strings of role identifiers 
{
  "Id": "string",
  "ExternalUserId": "string",
  "ContactGivenName": "string",
  "ContactSurname": "string",
  "ContactEmail": "user@example.com",
  "IdentityProviderId": "string",
  "IdentityProviderSpecificUserId": "string",
  "RoleIds": [
    "string"
  ]
}
In This Topic
TitleResults for “How to create a CRG?”Also Available in