--- title: "Client" description: "'Define OAuth2 Clients with keys and secrets for secure app access. Manage clients, enable flows, and protect your platform.' (Gitana 4.0)" product: "Gitana" version: "4.0" url: "/documentation/gitana/4.0/reference/types/client" --- # Client An Object 1. [Platform](/documentation/gitana/4.0/reference/types/platform.md) 2. [Client](/documentation/gitana/4.0/reference/types/client.md) ##### Table of Contents - [Overview](#top "Overview") - [Parent](#parent "Parent") - [Properties](#properties "Properties") - [Methods](#methods "Methods") - [Schema](#schema "Schema") A Client defines an entry point for applications to connect to your platform. Applications utilize a key and secret to identify themselves as a particular client of your platform. You can have as many Clients as you would like. Each client has a key/secret combination which the calling application will need to provide in order to assert their identity as the client. This prevents unknown applications from using your platform without your knowledge. Clients support the OAuth2 authentication flows. You can specify for each Client which flows you intend for it to support. You can also enable Open Driver authentication support for JavaScript/HTML5 applications running on the Cloud CMS hosted tier. Finally, you can at any point disable Clients if you suspect they are being tampered with or if you decide you would like to issue new credentials. > **Note:** Drop in one of our language drivers to accelerate your development. > Here are links to some of our popular [Cookbooks](/documentation/gitana/4.0/developers/cookbooks/overview.md) to help you get started! > > - [C#](/documentation/gitana/4.0/developers/cookbooks/csharp.md) > - [Go](/documentation/gitana/4.0/developers/cookbooks/go.md) > - [Java](/documentation/gitana/4.0/developers/cookbooks/java.md) > - [JavaScript](/documentation/gitana/4.0/developers/cookbooks/javascript2.md) > - [PHP](/documentation/gitana/4.0/developers/cookbooks/php.md) > - [Python](/documentation/gitana/4.0/developers/cookbooks/python.md) > - [Ruby](/documentation/gitana/4.0/developers/cookbooks/ruby.md) ## Parent This Client is contained within a [Platform](/documentation/gitana/4.0/reference/types/platform.md). ## Properties The following properties are available: | Property | Type | Default | Read-Only | Description | | --- | --- | --- | --- | --- | | \_doc | string | | No | The primary ID | | \_system | object | | No | Metadata maintained by the system | | accessTokenValiditySeconds | number | | No | | | allowAutoApprovalForImplicitFlow | boolean | | No | If true, then Cloud CMS will automatically approve the requested scopes when the user authenticates in the "implicit" flow. Normally, a successful authentication will take the user to a confirmation page where they can authorize the requested scopes. This skips that step. After authenticating, the scopes are automatically approved and the browser is redirected to the redirect URI. | | allowGuestLogin | boolean | | No | | | allowOpenDriverAuthentication | boolean | | No | Whether to enable "Open Driver" authentication. Open Driver authentication does not require the client secret to be present for client authorization in the "password" flow. Instead, it checks for valid domain URLs for the hosted application. | | authorizedGrantTypes | string | | No | An array of Strings which define the OAuth2 authorization flows that are supported by this Client. Valid values are: authorization\_code, implicit, password and refresh. | | defaultTenantId | string | | Yes | If this Client is the default Client for a Tenant, then this is the ID of that Tenant. | | domainUrls | array | | No | If you're using Open Driver authentication, then this is an array of URLs which identify valid HTTP "Referrer" (spelling) headers for the incoming request. This allows for a safety check to help ensure that the client application is running at a known address. Note: This is only a safeguard. But it isn't foolproof. It's still possible for malicious clients to fake HTTP "Referrer" headers if they wanted to. If you detect misuse of Client keys, you can disable the client and issue a new one. | | enabled | boolean | | No | | | isTenantDefault | boolean | | Yes | Whether this Client is the default Client for the tenant. Every Tenant has a default Client and it is best-practice not to share this Client information with anyone except the administrator of your platform. | | key | string | | No | | | refreshTokenValiditySeconds | number | | No | | | registeredRedirectUri | string | | No | If provided, this is the required redirect URI to be used for the "authorization code" flow. It is not required. OAuth2 allows the redirect URI to be passed in by the originating authorize request. However, if you want tighter security, you can specify the redirect URI here and enforce redirects only back to known pages. | | scope | string | | No | An array of strings that define the scopes of access that the user must have granted the caller in order to use this Client. The Cloud CMS driver requires the following scope: api. | | secret | string | | No | | ## Methods The following methods are available: - [Check Permission](#post-clients-clientid-permissions-permissionid-check "Check Permission") - [Check Single Authority](#post-clients-clientid-authorities-authorityid-check "Check Single Authority") - [Check multiple Authorities](#post-clients-authorities-check "Check multiple Authorities") - [Check multiple Permissions](#post-clients-permissions-check "Check multiple Permissions") - [Create Client](#post-clients "Create Client") - [Delete Client](#delete-clients-clientid "Delete Client") - [Delete Client](#post-clients-clientid-delete "Delete Client") - [Export Client](#post-clients-clientid-export "Export Client") - [Grant Authority](#post-clients-clientid-authorities-authorityid-grant "Grant Authority") - [Import Client](#post-clients-clientid-import "Import Client") - [Lists Client](#get-clients "Lists Client") - [Queries for Client](#post-clients-query "Queries for Client") - [Read ACL](#get-clients-clientid-acl-list "Read ACL") - [Read ACL for Principal](#get-clients-clientid-acl "Read ACL for Principal") - [Read Authorities Report](#post-clients-clientid-authorities "Read Authorities Report") - [Read Client](#get-clients-clientid "Read Client") - [Revoke Authority](#post-clients-clientid-authorities-authorityid-revoke "Revoke Authority") - [Update Client](#put-clients-clientid "Update Client") - [Update Client](#post-clients-clientid-update "Update Client") ### Check Permission Checks whether one or more authorities against the specified client are granted for a given set of users POST /clients/{clientId}/permissions/{permissionId}/check #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | | permissionId | true | string | The ID of the permission | | id | true | string | | #### Response ```json { "$ref": "#/components/schemas/checkPermission" } ``` ### Check Single Authority Checks whether a single authority is granted against the specified client for the given user POST /clients/{clientId}/authorities/{authorityId}/check #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | | authorityId | true | string | The ID or authority key for the authority | | id | true | string | | #### Response ```json { "type": "object", "description": "Check", "extends": "status", "properties": { "check": { "type": "boolean" }, "ok": null } } ``` ### Check multiple Authorities Checks whether one or more authorities against the specified client are granted for a given set of users POST /clients/authorities/check #### Parameters This function has no parameters. #### Response ```json { "type": "object", "description": "Check Multiple Authorities Out", "properties": { "checks": { "type": "array", "items": { "type": "object", "properties": { "permissionedId": { "type": "string" }, "principalId": { "type": "string" }, "authorityId": { "type": "string" }, "result": { "type": "boolean" } } } } } } ``` ### Check multiple Permissions Checks whether one or more permissions against the specified client are granted for a given set of users POST /clients/permissions/check #### Parameters This function has no parameters. #### Response ```json { "type": "object", "description": "Check Multiple Permissions Out", "properties": { "checks": { "type": "array", "items": { "type": "object", "properties": { "permissionedId": { "type": "string" }, "principalId": { "type": "string" }, "permissionId": { "type": "string" }, "result": { "type": "boolean" } } } } } } ``` ### Create Client Creates a new Client POST /clients #### Parameters This function has no parameters. #### Response ```json { "type": "object", "description": "Status of Operation", "properties": { "ok": { "type": "boolean", "description": "Indicates whether the operation succeeded or not" } } } ``` ### Delete Client Deletes an existing Client DELETE /clients/{clientId} #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | #### Response ```json { "type": "object", "description": "Status of Operation", "properties": { "ok": { "type": "boolean", "description": "Indicates whether the operation succeeded or not" } } } ``` ### Delete Client Deletes an existing Client POST /clients/{clientId}/delete #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | #### Response ```json { "type": "object", "description": "Status of Operation", "properties": { "ok": { "type": "boolean", "description": "Indicates whether the operation succeeded or not" } } } ``` ### Export Client Starts an export job for this resource POST /clients/{clientId}/export #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | | groupId | false | string | The Group ID to be assigned to the exported archive | | artifactId | false | string | The Artifact ID to be assigned to the exported archive | | versionId | false | string | The Version ID to be assigned to the exported archive | | vaultId | false | string | The ID of the vault where the exported archive should be saved | | schedule | false | string | Whether to run the job immediately or in the background (either 'synchronous' or 'asynchronous') | #### Response ```json { "type": "object", "description": "Export Configuration", "properties": { "startDate": { "type": "object", "description": "Only include objects whose modification date is after this time (epoch millis). This is used for partial or rolling exports." }, "endDate": { "type": "object", "description": "Only include objects whose modification date is before this time (epoch millis). This is used for partial or rolling exports." }, "startChangeset": { "type": "string", "description": "Only include data that is relevant to changesets at or beyond the specified changeset." }, "endChangeset": { "type": "string", "description": "Only include data that is relevant to changesets at or before the specified changeset." }, "includeACLs": { "type": "boolean", "default": true, "description": "Whether to include ACLs during export." }, "includeTeams": { "type": "boolean", "default": true, "description": "Whether to include Teams during export." }, "includeActivities": { "type": "boolean", "default": true, "description": "Whether to include Activities during export." }, "includeBinaries": { "type": "boolean", "default": true, "description": "Whether to include Binaries for data stores during export." }, "includeAttachments": { "type": "boolean", "default": true, "description": "Whether to include Attachments for Attachables during export." }, "artifactDependencies": { "type": "array", "items": { "type": "object" } }, "artifactIncludes": { "type": "array", "items": { "type": "object" } }, "forceIncludes": { "type": "boolean" } } } ``` ### Grant Authority Grants an authority against the specified client to a given user POST /clients/{clientId}/authorities/{authorityId}/grant #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | | authorityId | true | string | The ID or authority key for the authority | | id | true | string | | #### Response ```json { "type": "object", "description": "Status of Operation", "properties": { "ok": { "type": "boolean", "description": "Indicates whether the operation succeeded or not" } } } ``` ### Import Client Starts an import job for this resource POST /clients/{clientId}/import #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | | groupId | false | string | The Group ID to be assigned to the exported archive | | artifactId | false | string | The Artifact ID to be assigned to the exported archive | | versionId | false | string | The Version ID to be assigned to the exported archive | | vaultId | false | string | The ID of the vault where the exported archive should be saved | | schedule | false | string | Whether to run the job immediately or in the background (either 'synchronous' or 'asynchronous') | #### Response ```json { "type": "object", "description": "Import Configuration", "properties": { "includeACLs": { "type": "boolean", "default": true, "description": "Whether to include ACLs during import." }, "includeTeams": { "type": "boolean", "default": true, "description": "Whether to include Teams during import." }, "includeActivities": { "type": "boolean", "default": true, "description": "Whether to include Activities during import." }, "includeBinaries": { "type": "boolean", "default": true, "description": "Whether to include Binaries for data stores during import." }, "includeAttachments": { "type": "boolean", "default": true, "description": "Whether to include Attachments for Attachables during import." }, "strategy": { "type": "array", "items": { "type": "string" }, "default": "CLONE", "description": "Either CLONE or COPY_EVERYTHING. Use CLONE to keep the same IDs on import. Use COPY_EVERYTHING to generate all new IDs for all entries on every import." }, "substitutions": { "type": "string" } } } ``` ### Lists Client Retrieves a list of Client instances GET /clients #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | sort | false | object | Defines how to sort fields in the result set | | skip | false | number | Skips the result set cursor ahead the specified number of records | | limit | false | number | Specifies the number of records to be handed back in the result set | This method supports pagination. #### Response ```json { "type": "object", "description": "Result Map", "properties": { "total_rows": { "type": "number" }, "offset": { "type": "number" }, "size": { "type": "number" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/resultmap_client" } } } } ``` ### Queries for Client Queries for instances of type Client POST /clients/query #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | sort | false | object | Defines how to sort fields in the result set | | skip | false | number | Skips the result set cursor ahead the specified number of records | | limit | false | number | Specifies the number of records to be handed back in the result set | This method supports pagination. #### Response ```json { "type": "object", "description": "Result Map", "properties": { "total_rows": { "type": "number" }, "offset": { "type": "number" }, "size": { "type": "number" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/resultmap_client" } } } } ``` ### Read ACL Read the Access Control List for the specified client GET /clients/{clientId}/acl/list #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | #### Response ```json { "type": "object", "description": "Result Map of ACL entries", "properties": { "total_rows": { "type": "number" }, "offset": { "type": "number" }, "size": { "type": "number" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "_doc": { "type": "string", "title": "Principal ID" }, "name": { "type": "string", "title": "Principal Name" }, "type": { "type": "string", "title": "Principal Type" }, "domainId": { "type": "string" }, "domainQualifiedId": { "type": "string" }, "domainQualifiedName": { "type": "string" }, "principalId": { "type": "string", "title": "Principal ID" }, "userEmail": { "type": "string" }, "userFirstName": { "type": "string" }, "userLastName": { "type": "string" }, "authorities": { "type": "array", "title": "Authorities", "items": { "type": "string", "title": "Authority Key" } } } } } } } ``` ### Read ACL for Principal Read the Access Control List for the specified client and the given principal GET /clients/{clientId}/acl #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | | id | true | string | | #### Response ```json { "type": "object", "description": "Result Map of Authority Keys", "properties": { "total_rows": { "type": "number" }, "offset": { "type": "number" }, "size": { "type": "number" }, "rows": { "type": "array", "items": { "type": "string", "description": "Authority Key" } } } } ``` ### Read Authorities Report Read the Authorities Report for the specified client POST /clients/{clientId}/authorities #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | #### Response ```json { "type": "object", "description": "Authority Report", "properties": { "principalId": { "type": "object", "properties": { "id": { "type": "object", "properties": { "role-key": { "type": "string" }, "principal": { "type": "string" }, "permissioned": { "type": "string" }, "inheritsFrom": { "type": "object", "properties": { "id": { "type": "string" }, "principal": { "type": "string" }, "permissioned": { "type": "string" } } } } } } } } } ``` ### Read Client Reads an instance of a Client GET /clients/{clientId} #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | #### Response ```json { "type": "object", "extends": "document", "description": "Client", "container": "platform", "properties": { "key": { "type": "string", "required": true }, "secret": { "type": "string", "required": true }, "authorizedGrantTypes": { "type": "string", "enum": [ "authorization_code", "password", "implicit", "client_credentials", "refresh_token" ], "description": "An array of Strings which define the OAuth2 authorization flows that are supported by this Client. Valid values are: authorization_code, implicit, password and refresh." }, "scope": { "type": "string", "description": "An array of strings that define the scopes of access that the user must have granted the caller in order to use this Client. The Cloud CMS driver requires the following scope: api." }, "registeredRedirectUri": { "type": "string", "description": "If provided, this is the required redirect URI to be used for the \"authorization code\" flow. It is not required. OAuth2 allows the redirect URI to be passed in by the originating authorize request. However, if you want tighter security, you can specify the redirect URI here and enforce redirects only back to known pages." }, "domainUrls": { "type": "array", "items": { "type": "string" }, "description": "If you're using Open Driver authentication, then this is an array of URLs which identify valid HTTP \"Referrer\" (spelling) headers for the incoming request. This allows for a safety check to help ensure that the client application is running at a known address. Note: This is only a safeguard. But it isn't foolproof. It's still possible for malicious clients to fake HTTP \"Referrer\" headers if they wanted to. If you detect misuse of Client keys, you can disable the client and issue a new one." }, "isTenantDefault": { "type": "boolean", "readonly": true, "description": "Whether this Client is the default Client for the tenant. Every Tenant has a default Client and it is best-practice not to share this Client information with anyone except the administrator of your platform." }, "defaultTenantId": { "type": "string", "readonly": true, "description": "If this Client is the default Client for a Tenant, then this is the ID of that Tenant." }, "allowOpenDriverAuthentication": { "type": "boolean", "description": "Whether to enable \"Open Driver\" authentication. Open Driver authentication does not require the client secret to be present for client authorization in the \"password\" flow. Instead, it checks for valid domain URLs for the hosted application." }, "enabled": { "type": "boolean" }, "allowAutoApprovalForImplicitFlow": { "type": "boolean", "description": "If true, then Cloud CMS will automatically approve the requested scopes when the user authenticates in the \"implicit\" flow. Normally, a successful authentication will take the user to a confirmation page where they can authorize the requested scopes. This skips that step. After authenticating, the scopes are automatically approved and the browser is redirected to the redirect URI." }, "accessTokenValiditySeconds": { "type": "number" }, "refreshTokenValiditySeconds": { "type": "number" }, "allowGuestLogin": { "type": "boolean" }, "_doc": null, "_system": null } } ``` ### Revoke Authority Revokes an authority against the specified client from a given user POST /clients/{clientId}/authorities/{authorityId}/revoke #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | | authorityId | true | string | The ID or authority key for the authority | | id | true | string | | #### Response ```json { "type": "object", "description": "Status of Operation", "properties": { "ok": { "type": "boolean", "description": "Indicates whether the operation succeeded or not" } } } ``` ### Update Client Updates an existing Client PUT /clients/{clientId} #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | #### Response ```json { "type": "object", "description": "Status of Operation", "properties": { "ok": { "type": "boolean", "description": "Indicates whether the operation succeeded or not" } } } ``` ### Update Client Updates an existing Client POST /clients/{clientId}/update #### Parameters | Name | Required | Type | Description | | --- | --- | --- | --- | | clientId | true | string | The ID of the client | #### Response ```json { "type": "object", "description": "Status of Operation", "properties": { "ok": { "type": "boolean", "description": "Indicates whether the operation succeeded or not" } } } ``` ## Schema ```json { "type": "object", "extends": "document", "description": "Client", "container": "platform", "properties": { "key": { "type": "string", "required": true }, "secret": { "type": "string", "required": true }, "authorizedGrantTypes": { "type": "string", "enum": [ "authorization_code", "password", "implicit", "client_credentials", "refresh_token" ], "description": "An array of Strings which define the OAuth2 authorization flows that are supported by this Client. Valid values are: authorization_code, implicit, password and refresh." }, "scope": { "type": "string", "description": "An array of strings that define the scopes of access that the user must have granted the caller in order to use this Client. The Cloud CMS driver requires the following scope: api." }, "registeredRedirectUri": { "type": "string", "description": "If provided, this is the required redirect URI to be used for the \"authorization code\" flow. It is not required. OAuth2 allows the redirect URI to be passed in by the originating authorize request. However, if you want tighter security, you can specify the redirect URI here and enforce redirects only back to known pages." }, "domainUrls": { "type": "array", "items": { "type": "string" }, "description": "If you're using Open Driver authentication, then this is an array of URLs which identify valid HTTP \"Referrer\" (spelling) headers for the incoming request. This allows for a safety check to help ensure that the client application is running at a known address. Note: This is only a safeguard. But it isn't foolproof. It's still possible for malicious clients to fake HTTP \"Referrer\" headers if they wanted to. If you detect misuse of Client keys, you can disable the client and issue a new one." }, "isTenantDefault": { "type": "boolean", "readonly": true, "description": "Whether this Client is the default Client for the tenant. Every Tenant has a default Client and it is best-practice not to share this Client information with anyone except the administrator of your platform." }, "defaultTenantId": { "type": "string", "readonly": true, "description": "If this Client is the default Client for a Tenant, then this is the ID of that Tenant." }, "allowOpenDriverAuthentication": { "type": "boolean", "description": "Whether to enable \"Open Driver\" authentication. Open Driver authentication does not require the client secret to be present for client authorization in the \"password\" flow. Instead, it checks for valid domain URLs for the hosted application." }, "enabled": { "type": "boolean" }, "allowAutoApprovalForImplicitFlow": { "type": "boolean", "description": "If true, then Cloud CMS will automatically approve the requested scopes when the user authenticates in the \"implicit\" flow. Normally, a successful authentication will take the user to a confirmation page where they can authorize the requested scopes. This skips that step. After authenticating, the scopes are automatically approved and the browser is redirected to the redirect URI." }, "accessTokenValiditySeconds": { "type": "number" }, "refreshTokenValiditySeconds": { "type": "number" }, "allowGuestLogin": { "type": "boolean" }, "_doc": null, "_system": null }, "id": "client" } ```