Hybrid Clients
- Last UpdatedJul 27, 2023
- 8 minute read
Hybrid clients are used in typical, thick MVC clients with the presence of a user. These clients are issued an unique identifier and secret upon creation, which are later used for authentication against the platform. More than one secret can be created for a client. Hybrid clients can be issued refresh tokens, if requested, alongside access tokens. Refresh tokens typically have a longer lifetime than access tokens, and are used to request a new access token on behalf of the user without them having to log in. It is highly suggested that both the client secret and the refresh token be stored in a secure location. Note: Currently the refresh token is not supported for the hybrid clients.
List All Hybrid Clients
Returns a list of hybrid clients from a tenant. Optionally, returns a list of requested clients. Total number of clients in the tenant set in the Total-Count header
Request
GET /api/v1/Tenants/{tenantId}/HybridClients
?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 | HybridClient[] | List of all hybrid clients found |
| 401 | ErrorResponse | Unauthorized. |
| 403 | ErrorResponse | Forbidden. |
| 404 | ErrorResponse | Tenant not found |
| 500 | ErrorResponse | Internal server error. |
Example response body
200 Response (HybridClient[])
[
{
"RedirectUris": [
"string"
],
"PostLogoutRedirectUris": [
"string"
],
"ClientUri": "string",
"LogoUri": "string",
"Id": "string",
"Name": "string",
"Enabled": true,
"AccessTokenLifetime": 0,
"Tags": [
"string"
],
"AllowOfflineAccess": true,
"AllowAccessTokensViaBrowser": true
}
]
Authorization
Allowed for these roles:
- Tenant Member
Get Total Count of Hybrid Clients
Returns the total number of hybrid clients in a tenant. Optionally, checks based on a list of requested clients. 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}/HybridClients
?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 | Hybrid client secrets 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 Hybrid Client
Creates a hybrid client. A client unique 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 unique identifiers in a tenant. Currently there is a limit of 50000 clients (of all types) per tenant.
Request
POST /api/v1/Tenants/{tenantId}/HybridClients
Parameters
string tenantId
Tenant identifier.
Request Body
HybridClientCreate object
{
"AllowOfflineAccess": true,
"AllowAccessTokensViaBrowser": true,
"RedirectUris": [
"string"
],
"PostLogoutRedirectUris": [
"string"
],
"ClientUri": "string",
"LogoUri": "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 | HybridClientCreateResponse | Information about created hybrid 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 (HybridClientCreateResponse)
{
"Secret": "string",
"Id": 0,
"Description": "string",
"ExpirationDate": "2019-08-24T14:15:22Z",
"Client": {
"RedirectUris": [
"string"
],
"PostLogoutRedirectUris": [
"string"
],
"ClientUri": "string",
"LogoUri": "string",
"Id": "string",
"Name": "string",
"Enabled": true,
"AccessTokenLifetime": 0,
"Tags": [
"string"
],
"AllowOfflineAccess": true,
"AllowAccessTokensViaBrowser": true
}
}
Authorization
Allowed for these roles:
- Tenant Administrator
Get Hybrid Client
Returns a hybrid client from a tenant.
Request
GET /api/v1/Tenants/{tenantId}/HybridClients/{clientId}
Parameters
string tenantId
Tenant identifier.string clientId
Client identifier.
Response
| Status Code | Body Type | Description |
|---|---|---|
| 200 | HybridClient | Information about specified hybrid client |
| 401 | ErrorResponse | Unauthorized. |
| 403 | ErrorResponse | Forbidden. |
| 404 | ErrorResponse | Client or tenant not found |
| 500 | ErrorResponse | Internal server error. |
Example response body
200 Response (HybridClient)
{
"RedirectUris": [
"string"
],
"PostLogoutRedirectUris": [
"string"
],
"ClientUri": "string",
"LogoUri": "string",
"Id": "string",
"Name": "string",
"Enabled": true,
"AccessTokenLifetime": 0,
"Tags": [
"string"
],
"AllowOfflineAccess": true,
"AllowAccessTokensViaBrowser": true
}
Authorization
Allowed for these roles:
- Self
- Tenant Member
Get Header for Hybrid Client
Validates that a hybrid 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}/HybridClients/{clientId}
Parameters
string tenantId
Tenant identifier.string clientId
Client identifier.
Response
| Status Code | Body Type | Description |
|---|---|---|
| 200 | None | Header for specified hybrid 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 Hybrid Client
Updates a hybrid client. It can take up to one hour for these values to manifest in the authentication process.
Request
PUT /api/v1/Tenants/{tenantId}/HybridClients/{clientId}
Parameters
string tenantId
Tenant identifier.string clientId
Client identifier.
Request Body
HybridClient object. Properties that are not set or are null will not be changed.
{
"RedirectUris": [
"string"
],
"PostLogoutRedirectUris": [
"string"
],
"ClientUri": "string",
"LogoUri": "string",
"Id": "string",
"Name": "string",
"Enabled": true,
"AccessTokenLifetime": 0,
"Tags": [
"string"
],
"AllowOfflineAccess": true,
"AllowAccessTokensViaBrowser": true
}
Response
| Status Code | Body Type | Description |
|---|---|---|
| 200 | HybridClient | Information about updated hybrid 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 (HybridClient)
{
"RedirectUris": [
"string"
],
"PostLogoutRedirectUris": [
"string"
],
"ClientUri": "string",
"LogoUri": "string",
"Id": "string",
"Name": "string",
"Enabled": true,
"AccessTokenLifetime": 0,
"Tags": [
"string"
],
"AllowOfflineAccess": true,
"AllowAccessTokensViaBrowser": true
}
Authorization
Allowed for these roles:
- Tenant Administrator
Delete Hybrid Client
Deletes a hybrid 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. Refresh tokens issued to this will be valid up to one hour after deletion.
Request
DELETE /api/v1/Tenants/{tenantId}/HybridClients/{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
HybridClientCreateResponse
Secret information returned after a hybrid client is created
Properties
| Property Name | Data Type | Required | Nullable | Description |
|---|---|---|---|---|
| Secret | string | false | true | Client secret |
| Id | int32 | false | false | Secret identifier |
| 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 | HybridClient | false | true | Created hybrid client object |
{
"Secret": "string",
"Id": 0,
"Description": "string",
"ExpirationDate": "2019-08-24T14:15:22Z",
"Client": {
"RedirectUris": [
"string"
],
"PostLogoutRedirectUris": [
"string"
],
"ClientUri": "string",
"LogoUri": "string",
"Id": "string",
"Name": "string",
"Enabled": true,
"AccessTokenLifetime": 0,
"Tags": [
"string"
],
"AllowOfflineAccess": true,
"AllowAccessTokensViaBrowser": true
}
}
HybridClient
Object used for hybrid clients
Properties
| Property Name | Data Type | Required | Nullable | Description |
|---|---|---|---|---|
| RedirectUris | string[] | false | true | Note: Required when creating a client, but optional when updating a client. Allowed URIs to which return tokens or authorization codes can be returned. Wildcards are ignored. URIs must match exactly what you are redirecting to after login. If URIs do not match, the authentication process will fail with a bad_client error. Maximum 10 per client. |
| PostLogoutRedirectUris | string[] | false | true | Allowed URIs to redirect to after logout. Wildcards are ignored. URIs must match exactly what you are redirecting to after logout. Maximum 10 per client. |
| ClientUri | string | false | true | URI to a page with information about client (used on consent screen) |
| LogoUri | string | false | true | URI to client logo (used on consent screen) |
| 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 |
| AllowOfflineAccess | boolean | false | true | Whether this client can request refresh tokens, by providing the offline_access scope. |
| AllowAccessTokensViaBrowser | boolean | false | true | Whether this hybrid client is allowed to receive access tokens through the browser. This is useful to harden flows that allow multiple response types (for example, by disallowing a hybrid flow client that is supposed to use code id_token to add the token response type, thus leaking the token to the browser). |
{
"RedirectUris": [
"string"
],
"PostLogoutRedirectUris": [
"string"
],
"ClientUri": "string",
"LogoUri": "string",
"Id": "string",
"Name": "string",
"Enabled": true,
"AccessTokenLifetime": 0,
"Tags": [
"string"
],
"AllowOfflineAccess": true,
"AllowAccessTokensViaBrowser": true
}
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
}
HybridClientCreate
Object used during hybrid client creation
Properties
| Property Name | Data Type | Required | Nullable | Description |
|---|---|---|---|---|
| AllowOfflineAccess | boolean | false | true | Whether this client can request refresh tokens, by providing the offline_access scope. |
| AllowAccessTokensViaBrowser | boolean | false | true | Whether this hybrid client is allowed to receive access tokens through the browser. This is useful to harden flows that allow multiple response types (for example, by disallowing a hybrid flow client that is supposed to use code id_token to add the token response type, thus leaking the token to the browser). |
| RedirectUris | string[] | false | true | Note: Required when creating a client, but optional when updating a client. Allowed URIs to which return tokens or authorization codes can be returned. Wildcards are ignored. URIs must match exactly what you are redirecting to after login. If URIs do not match, the authentication process will fail with a bad_client error. Maximum 10 per client. |
| PostLogoutRedirectUris | string[] | false | true | Allowed URIs to redirect to after logout. Wildcards are ignored. URIs must match exactly what you are redirecting to after logout. Maximum 10 per client. |
| ClientUri | string | false | true | URI to a page with information about client (used on consent screen) |
| LogoUri | string | false | true | URI to client logo (used on consent screen) |
| 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 |
| 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. |
{
"AllowOfflineAccess": true,
"AllowAccessTokensViaBrowser": true,
"RedirectUris": [
"string"
],
"PostLogoutRedirectUris": [
"string"
],
"ClientUri": "string",
"LogoUri": "string",
"Id": "string",
"Name": "string",
"Enabled": true,
"AccessTokenLifetime": 0,
"Tags": [
"string"
],
"SecretDescription": "string",
"SecretExpirationDate": "2019-08-24T14:15:22Z"
}