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 Roles

Save PDF
Save selected topicSave selected topic and subtopicsSave all topics
Share
Share to emailCopy topic URL
  • Last UpdatedJan 20, 2023
  • 6 minute read

APIs for creating, getting, updating, and deleting roles on a tenant

List Roles

Returns all roles for a tenant including roles for any communities that the tenant belongs.

Request

GET /api/v1/Tenants/{tenantId}/Roles
?query={query}&skip={skip}&count={count}&roleTypeId={roleTypeId}

Parameters

string tenantId
Tenant identifier.

[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] string roleTypeId
Role type identifier

Response

Status Code Body Type Description
200 Role[] List of roles found
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse Tenant not found
500 ErrorResponse Internal server error.

Example response body

200 Response (Role[])

[
  {
    "Id": "string",
    "Name": "string",
    "Description": "string",
    "RoleScope": 0,
    "TenantId": "string",
    "CommunityId": "string",
    "RoleTypeId": "string"
  }
]

Authorization

Allowed for these roles:

  • Tenant Member

Get Header for Roles

Returns header for roles to get the total number of roles for a given tenant, including community roles for any community the tenant is joined.

Request

HEAD /api/v1/Tenants/{tenantId}/Roles

Parameters

string tenantId
Tenant identifier.

Response

Status Code Body Type Description
200 None Headers for roles found
401 None Unauthorized.
403 None Forbidden.
404 None Tenant not found
500 None Internal server error.

Authorization

Allowed for these roles:

  • Tenant Member

Create Role on Tenant

Creates a new tenant role.

Request

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

Parameters

string tenantId
Tenant identifier.

Request Body

Role to create

{
  "Id": "string",
  "Name": "string",
  "Description": "string",
  "RoleScope": 0,
  "TenantId": "string",
  "CommunityId": "string",
  "RoleTypeId": "string"
}

Response

Status Code Body Type Description
201 Role Role created
302 None A role with the same identifier or name already exists in the tenant.
400 ErrorResponse Missing or invalid inputs.
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse Tenant or role not found
408 ErrorResponse Operation timed out.
409 ErrorResponse A role with some matching values already exists in tenant.
500 ErrorResponse Internal server error.

Example response body

201 Response (Role)

{
  "Id": "string",
  "Name": "string",
  "Description": "string",
  "RoleScope": 0,
  "TenantId": "string",
  "CommunityId": "string",
  "RoleTypeId": "string"
}

Authorization

Allowed for these roles:

  • Tenant Administrator

List Users for a Given Role

Returns all users for a given role.

Request

GET /api/v1/Tenants/{tenantId}/Roles/{roleId}/users

Parameters

string tenantId
Tenant identifier.

string roleId
Role identifier

Response

Status Code Body Type Description
200 User[] Users for a given role
401 None Unauthorized.
403 None Forbidden.
404 None Tenant or role not found
500 None 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 for a Given Role

Returns total number of users for a given role.

Request

HEAD /api/v1/Tenants/{tenantId}/Roles/{roleId}/users

Parameters

string tenantId
Tenant identifier.

string roleId
Role identifier

Response

Status Code Body Type Description
200 None Headers for roles found
401 None Unauthorized.
403 None Forbidden.
404 None Tenant or role not found
500 None Internal server error.

Authorization

Allowed for these roles:

  • Tenant Member

List All Clients for a Given Role

Returns all the clients for a given role.

Request

GET /api/v1/Tenants/{tenantId}/Roles/{roleId}/clientcredentialclients

Parameters

string tenantId
Tenant identifier.

string roleId
Role identifier

Response

Status Code Body Type Description
200 ClientCredentialClient[] Clients for a given role
401 None Unauthorized.
403 None Forbidden.
404 None Tenant or role not found
500 None Internal server error.

Example response body

200 Response (ClientCredentialClient[])

[
  {
    "Id": "string",
    "Name": "string",
    "Enabled": true,
    "AccessTokenLifetime": 0,
    "Tags": [
      "string"
    ],
    "RoleIds": [
      "string"
    ]
  }
]

Authorization

Allowed for these roles:

  • Tenant Member

Get Count of Clients for a Given Role

Returns the total number of clients for a given role.

Request

HEAD /api/v1/Tenants/{tenantId}/Roles/{roleId}/clientcredentialclients

Parameters

string tenantId
Tenant identifier.

string roleId
Role identifier

Response

Status Code Body Type Description
200 None Headers for the total number of clients for a given role
401 None Unauthorized.
403 None Forbidden.
404 None Tenant or role not found
500 None Internal server error.

Authorization

Allowed for these roles:

  • Tenant Member

Get Role

Returns the specified role.

Request

GET /api/v1/Tenants/{tenantId}/Roles/{roleId}

Parameters

string tenantId
Tenant identifier.

string roleId
Role identifier

Response

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

Example response body

200 Response (Role)

{
  "Id": "string",
  "Name": "string",
  "Description": "string",
  "RoleScope": 0,
  "TenantId": "string",
  "CommunityId": "string",
  "RoleTypeId": "string"
}

Authorization

Allowed for these roles:

  • Tenant Member

Get Header for a Given Role

Returns the header for a role on a given tenant.

Request

HEAD /api/v1/Tenants/{tenantId}/Roles/{roleId}

Parameters

string tenantId
Tenant identifier.

string roleId
Provider identifier

Response

Status Code Body Type Description
200 None Header for role specified
401 None Unauthorized.
403 None Forbidden.
404 None Identity provider or tenant not found
500 None Internal server error.

Authorization

Allowed for these roles:

  • Tenant Member

Update Role on Tenant

Updates a role for a tenant.

Request

PUT /api/v1/Tenants/{tenantId}/Roles/{roleId}

Parameters

string tenantId
Tenant identifier.

string roleId
Role identifier

Request Body

Role to update

{
  "Id": "string",
  "Name": "string",
  "Description": "string",
  "RoleScope": 0,
  "TenantId": "string",
  "CommunityId": "string",
  "RoleTypeId": "string"
}

Response

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

Example response body

200 Response (Role)

{
  "Id": "string",
  "Name": "string",
  "Description": "string",
  "RoleScope": 0,
  "TenantId": "string",
  "CommunityId": "string",
  "RoleTypeId": "string"
}

Authorization

Allowed for these roles:

  • Tenant Administrator

Delete Tenant Role

Deletes any tenant-scoped, non built-in role by its role identifier.

Request

DELETE /api/v1/Tenants/{tenantId}/Roles/{roleId}

Parameters

string tenantId
Tenant identifier.

string roleId
Role identifier

Response

Status Code Body Type Description
204 None No content
400 ErrorResponse Missing or invalid inputs.
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse Identity provider or tenant not found
408 ErrorResponse Operation timed out.
500 ErrorResponse Internal server error.

Authorization

Allowed for these roles:

  • Tenant Administrator

Definitions

Role

Object for retrieving a role

Properties

Property Name Data Type Required Nullable Description
Id string false true Role identifier. Generated by the server upon creation.
Name string false true Role name. This cannot be empty.
Description string false true Role description
RoleScope RoleScope false true Role scope
TenantId string false true Tenant identifier, if this is a Tenant Role. Otherwise, set to null.
CommunityId string false true Community identifier, if this is a Community Role. Otherwise set to null.
RoleTypeId string false true Role type identifier for built-in roles 
{
  "Id": "string",
  "Name": "string",
  "Description": "string",
  "RoleScope": 0,
  "TenantId": "string",
  "CommunityId": "string",
  "RoleTypeId": "string"
}

RoleScope

The object that represents the scope of a given role

Enumerated Values

Property Value
None 0
Tenant 1
Community 2
Cluster 3

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
}

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"
  ]
}

ClientCredentialClient

Object to return or update a ClientCredentialClient

Properties

Property Name Data Type Required Nullable Description
Id string false true Client identifier for this client. This identifier should be a GUID.
Name string false true Name of client
Enabled boolean false true Whether client is enabled. Client can be used for authentication if set to true. Client cannot be used for authentication if set to false.
AccessTokenLifetime int32 false true Lifetime of access token issued for this client after authentication. Minimum 60 seconds. Maximum 3600 seconds. Defaults to 3600 seconds.
Tags string[] false true Tags for AVEVA internal use only
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",
  "Name": "string",
  "Enabled": true,
  "AccessTokenLifetime": 0,
  "Tags": [
    "string"
  ],
  "RoleIds": [
    "string"
  ]
}
In This Topic
TitleResults for “How to create a CRG?”Also Available in