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

Client Credential Clients

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

Client credential clients are used for machine-to-machine communication without the presence of a user. These clients are issued an identifier and secret upon creation, which are later used for authentication against the platform. More than one secret can be created for a client. Because they access resources on the platform and are not associated to users, these clients can be assigned any of the roles in the tenant. We suggest following a least privilege strategy when assigning roles to these clients, as they are more likely to operate in remote machines with a wider attack surface.

List all Client Credential Clients

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

Request

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

Parameters

string tenantId
Tenant identifier.

[optional] array id
Unordered list of identifiers for all clients to get. Empty or whitespace identifiers will be ignored.

[optional] array tag
Only return clients that have these tags.

[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 ClientCredentialClient[] Client credential clients found
207 ClientCredentialClientMultiStatusResponse Client credential clients found
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse Tenant not found
500 ErrorResponse 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 Total Count of Clients

Returns the total number of client credential clients in a tenant. Optionally, check based on a list of requested client identifiers. 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}/ClientCredentialClients
?id={id}&tag={tag}

Parameters

string tenantId
Tenant identifier.

[optional] array id
Unordered list of identifiers for all clients to get. Empty or whitespace identifiers will be ignored.

[optional] array tag
Only return clients that have these tags.

Response

Status Code Body Type Description
200 None Client credential client headers found
401 None Unauthorized.
403 None Forbidden.
404 None Client or tenant not found
500 None Internal server error.

Authorization

Allowed for these roles:

  • Tenant Member

Create Client Credential Client

Creates a client credential client. A client identifier and client secret will be generated to perform authentication. Make sure to store the secret somewhere safe as we do not store the actual value after the creation step. If you do not have access to the secret value, we suggest deleting the secret and adding a new one for this client. Clients have identifiers in a tenant. Currently there is a limit of 50000 clients (of any type) per tenant.

Request

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

Parameters

string tenantId
Tenant identifier.

Request Body

ClientCredentialClientCreate object

{
  "RoleIds": [
    "string"
  ],
  "Id": "string",
  "Name": "string",
  "Enabled": true,
  "AccessTokenLifetime": 0,
  "Tags": [
    "string"
  ],
  "SecretDescription": "string",
  "SecretExpirationDate": "2019-08-24T14:15:22Z"
}

Response

Status Code Body Type Description
201 ClientCredentialClientCreateResponse Client credential client details for created client
400 ErrorResponse Missing or invalid inputs, or client limit exceeded
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse Tenant not found
408 ErrorResponse Operation timed out.
409 ErrorResponse Client identifier already exists
500 ErrorResponse Internal server error.

Example response body

201 Response (ClientCredentialClientCreateResponse)

{
  "Secret": "string",
  "Id": 0,
  "Description": "string",
  "ExpirationDate": "2019-08-24T14:15:22Z",
  "Client": {
    "Id": "string",
    "Name": "string",
    "Enabled": true,
    "AccessTokenLifetime": 0,
    "Tags": [
      "string"
    ],
    "RoleIds": [
      "string"
    ]
  }
}

Authorization

Allowed for these roles:

  • Tenant Administrator

Get Client Credential Client

Returns a client credential client.

Request

GET /api/v1/Tenants/{tenantId}/ClientCredentialClients/{clientId}

Parameters

string tenantId
Tenant identifier.

string clientId
Client identifier.

Response

Status Code Body Type Description
200 ClientCredentialClient Client credential client details for the specified client
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse Client or tenant not found
500 ErrorResponse 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:

  • Self
  • Tenant Member

Get Header for Client Credential Client

Validates that a client credential client exists. This method is identical to the GET method but it does not return any objects in the body.

Request

HEAD /api/v1/Tenants/{tenantId}/ClientCredentialClients/{clientId}

Parameters

string tenantId
Tenant identifier.

string clientId
Client identifier.

Response

Status Code Body Type Description
200 None Header for the specified client credential client
401 None Unauthorized.
403 None Forbidden.
404 None Client or tenant not found
500 None Internal server error.

Authorization

Allowed for these roles:

  • Self
  • Tenant Member

Update Client Credential Client

Updates a client credential client. It can take up to one hour for these values to manifest in the authentication process.

Request

PUT /api/v1/Tenants/{tenantId}/ClientCredentialClients/{clientId}

Parameters

string tenantId
Tenant identifier.

string clientId
Client identifier.

Request Body

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

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

Response

Status Code Body Type Description
200 ClientCredentialClient Client credential client details for updated client
400 ErrorResponse Missing or invalid inputs.
401 ErrorResponse Unauthorized.
403 ErrorResponse Forbidden.
404 ErrorResponse Client or tenant not found
408 ErrorResponse Operation timed out.
500 ErrorResponse 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 Administrator

Delete Client Credential Client

Deletes a client credential client. It can take up to one hour for deletion to manifest in the authentication process. Access tokens issued to this client will be valid until their expiration.

Request

DELETE /api/v1/Tenants/{tenantId}/ClientCredentialClients/{clientId}

Parameters

string tenantId
Tenant identifier.

string clientId
Client identifier.

Response

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

Authorization

Allowed for these roles:

  • Tenant Administrator

Definitions

ClientCredentialClientCreateResponse

Secret information returned after a client credential client is created

Properties

Property Name Data Type Required Nullable Description
Secret string false true Client secret
Id int32 false false Identifier of the client secret
Description string false true Description for the initial secret for the client
ExpirationDate date-time false true Expiration date for the initial secret for the client
Client ClientCredentialClient false true Created client credential client 
{
  "Secret": "string",
  "Id": 0,
  "Description": "string",
  "ExpirationDate": "2019-08-24T14:15:22Z",
  "Client": {
    "Id": "string",
    "Name": "string",
    "Enabled": true,
    "AccessTokenLifetime": 0,
    "Tags": [
      "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"
  ]
}

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
}

ClientCredentialClientCreate

Object used during client creation

Properties

Property Name Data Type Required Nullable Description
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 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
SecretDescription string false true Description for the initial secret for the client. Ensure that this is descriptive enough, as it will be the only way to distinguish between multiple secrets and their usage for a client.
SecretExpirationDate date-time false true Expiration date for the initial secret for the client. If set to null the secret will never expire. We advise against such practice. 
{
  "RoleIds": [
    "string"
  ],
  "Id": "string",
  "Name": "string",
  "Enabled": true,
  "AccessTokenLifetime": 0,
  "Tags": [
    "string"
  ],
  "SecretDescription": "string",
  "SecretExpirationDate": "2019-08-24T14:15:22Z"
}

ClientCredentialClientMultiStatusResponse

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 [ClientCredentialClient] false true Data representing client credentials 
{
  "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",
      "Name": "string",
      "Enabled": true,
      "AccessTokenLifetime": 0,
      "Tags": [
        "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
}
In This Topic
TitleResults for “How to create a CRG?”Also Available in