clients

7 endpoints

GET/rest/clients

List clients

Returns a list of registered OAuth clients. Hidden clients are excluded from the results.

Parameters

Query Parameters

name

Optional

string

Client name

name:contains

Optional

string

Client name. Search for results that contain the specified characters in this parameter.

description:contains

Optional

string

Client description. Search for results that contain the specified characters in this parameter.

orderBy

Optional

string[]

Sorting options

offset

Optional

integer

Offset

limit

Optional

integer

Limit

with

Optional

string

With parameters

mode

Optional

string

Determines the detail level of the response body.

Responses

Returns a paginated list of OAuth client records.

data

Client[]

Required

string

Unique Client identifier

name

Required

string

Display name of the client application

description

string

Human-readable description of the client application and its purpose

redirectUri

string

Redirect URL of this client

scope

string

API entities which this client can access

flag

integer

Flags for Client. e.g. NO_CONSENT:1, DISABLED:2, HIDDEN:4, NO_EXPIRY_TOKEN :8

flow

integer

Oauth flow for this client.
e.g. AUTH_CODE:1, CLIENT_CREDENTIAL:2, SIGNATURE:4, REFRESH_TOKEN:8

signatureKey

string

Secret key used to sign requests made by this client

accessTokenLifetime

integer

Life time for access token of client in hours. e.g. 5=5 hours

refreshTokenLifetime

integer

Life time for refresh token of client in hours

whiteList

string

List of applications on the device that the client can call out to

askPin

integer

Indicates whether a PIN should be requested of the user using this client

pinTimeout

integer

Time out for pin of client in minutes

maxPinAttempts

integer

Max attempts that user can try to enter PIN before wipe occurs

type

integer

Client Type. e.g. ACCELLION:1, MOBILE:2, OUTLOOK:4, SYNC:8, IMPORTED:32

touchId

boolean

Indicates whether touch Id is enabled

clipboardEnabled

boolean

Indicates whether clipboard is enabled

autoUpdate

boolean

Indicates whether auto update is enabled

installer

string

Installer information for the client

emailMatch

boolean

Indicates whether the external email matches a Kiteworks email

minVersion

integer

Minimum API version required by this client to operate correctly

links

string[]

HATEOAS links associated with the entity

metadata

MetaData

total

integer

Total number of items available.

limit

integer

Maximum number of items returned per page.

offset

integer

Number of items skipped before the current page.

Request blocked by WAF

Empty response body.

Shell

curl -X GET \
  "https://{instance}.kiteworks.com/rest/clients" \
  -H "Authorization: Bearer YOUR_TOKEN"

Python

import requests

url = "https://{instance}.kiteworks.com/rest/clients"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())

Responses

{ "data": [ { "id": "mobile_app_ios", "name": "iOS Mobile App", "description": "Company iOS mobile client", "redirect_uri": "https://example.com/callback", "scope": "*", "flag": 0, "flow": 1, "access_token_lifetime": 24, "refresh_token_lifetime": 720, "type": 2, "touch_id": true, "min_version": 28 }, { "id": "custom_integration", "name": "Custom Integration", "description": "Third-party integration client", "redirect_uri": "https://integration.example.com/callback", "scope": "files folders", "flag": 0, "flow": 1, "access_token_lifetime": 8, "refresh_token_lifetime": 168, "type": 0, "touch_id": false, "min_version": 28 } ], "total": 2, "page": 1, "pageSize": 20 }

// Error - No Body

POST/rest/clients

Create a client

Creates a new OAuth client (e.g. a custom mobile app). The response includes the plain-text client_secret, which is only returned once at creation time and cannot be retrieved again.

Parameters

Query Parameters

returnEntity

Optional

boolean

If set to true, returns information about the newly created entity.

mode

Optional

string

Determines the detail level of the response body.

Request Body

name

Required

string

Display name of the client application

description

Required

string

Human-readable description of the client application and its purpose

redirectUri

Required

string

Where the server send the code that client can redeem access token.
e.g. https://HOST/rest/callback.html

scope

Required

string

API entities which this client can access

signatureKey

string

Secret key used to sign requests made by this client

accessTokenLifetime

integer

Life time for access token of client in hours. e.g. 5=5 hours

refreshTokenLifetime

integer

Life time for refresh token of client in hours

addLinks

boolean

Indicates whether HATEOAS links should be included in the response

Responses

Returns the newly created client record, including the plain-text client_secret.

Required

string

Unique Client identifier

name

Required

string

Display name of the client application

description

string

Human-readable description of the client application and its purpose

redirectUri

string

Redirect URL of this client

scope

string

API entities which this client can access

flag

integer

Flags for Client. e.g. NO_CONSENT:1, DISABLED:2, HIDDEN:4, NO_EXPIRY_TOKEN :8

flow

integer

Oauth flow for this client.
e.g. AUTH_CODE:1, CLIENT_CREDENTIAL:2, SIGNATURE:4, REFRESH_TOKEN:8

signatureKey

string

Secret key used to sign requests made by this client

accessTokenLifetime

integer

Life time for access token of client in hours. e.g. 5=5 hours

refreshTokenLifetime

integer

Life time for refresh token of client in hours

whiteList

string

List of applications on the device that the client can call out to

askPin

integer

Indicates whether a PIN should be requested of the user using this client

pinTimeout

integer

Time out for pin of client in minutes

maxPinAttempts

integer

Max attempts that user can try to enter PIN before wipe occurs

type

integer

Client Type. e.g. ACCELLION:1, MOBILE:2, OUTLOOK:4, SYNC:8, IMPORTED:32

touchId

boolean

Indicates whether touch Id is enabled

clipboardEnabled

boolean

Indicates whether clipboard is enabled

autoUpdate

boolean

Indicates whether auto update is enabled

installer

string

Installer information for the client

emailMatch

boolean

Indicates whether the external email matches a Kiteworks email

minVersion

integer

Minimum API version required by this client to operate correctly

links

string[]

HATEOAS links associated with the entity

clientSecret

string

Plain-text client secret returned only at creation time

Conflict

Possible error codes: ERR_ENTITY_EXISTS

error

Error[]

code

string

Error code

message

string

Error message

Unprocessable Content

Possible error codes: ERR_INPUT_REQUIRED, ERR_INPUT_NOT_INTEGER, ERR_INPUT_MIN_VALUE

error

Error[]

code

string

Error code

message

string

Error message

Request blocked by WAF

Empty response body.

Shell

curl -X POST \
  "https://{instance}.kiteworks.com/rest/clients" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "name": "string",
         "description": "string",
         "redirectUri": "string",
         "scope": "string",
         "signatureKey": "string",
         "accessTokenLifetime": 1
       }'

Python

import requests

url = "https://{instance}.kiteworks.com/rest/clients"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "name": "string",
  "description": "string",
  "redirectUri": "string",
  "scope": "string",
  "signatureKey": "string",
  "accessTokenLifetime": 1
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

Responses

{ "id": "custom_integration", "client_secret": "p1a2i3n4t5e6x7t8s9e0c", "name": "Custom Integration", "description": "Third-party integration client", "redirect_uri": "https://integration.example.com/callback", "scope": "files folders", "flag": 0, "flow": 1, "access_token_lifetime": 8, "refresh_token_lifetime": 168, "type": 0, "touch_id": false, "min_version": 28 }

{ "errors": { "code": "ERR_ENTITY_EXISTS", "message": "Entity exists" } }

{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }

{ "errors": { "code": "ERR_INPUT_NOT_INTEGER", "message": "Input is not a valid integer" } }

{ "errors": { "code": "ERR_INPUT_MIN_VALUE", "message": "The specified input below the minimum allowed value." } }

// Error - No Body

GET/rest/clients/me

Get current client

Returns the settings of the OAuth client used to make the current request (e.g. pin timeout, token lifetime).

This endpoint requires no parameters.

Responses

Returns the OAuth client record for the client making the request.

Required

string

Unique Client identifier

name

Required

string

Display name of the client application

description

string

Human-readable description of the client application and its purpose

redirectUri

string

Redirect URL of this client

scope

string

API entities which this client can access

flag

integer

Flags for Client. e.g. NO_CONSENT:1, DISABLED:2, HIDDEN:4, NO_EXPIRY_TOKEN :8

flow

integer

Oauth flow for this client.
e.g. AUTH_CODE:1, CLIENT_CREDENTIAL:2, SIGNATURE:4, REFRESH_TOKEN:8

signatureKey

string

Secret key used to sign requests made by this client

accessTokenLifetime

integer

Life time for access token of client in hours. e.g. 5=5 hours

refreshTokenLifetime

integer

Life time for refresh token of client in hours

whiteList

string

List of applications on the device that the client can call out to

askPin

integer

Indicates whether a PIN should be requested of the user using this client

pinTimeout

integer

Time out for pin of client in minutes

maxPinAttempts

integer

Max attempts that user can try to enter PIN before wipe occurs

type

integer

Client Type. e.g. ACCELLION:1, MOBILE:2, OUTLOOK:4, SYNC:8, IMPORTED:32

touchId

boolean

Indicates whether touch Id is enabled

clipboardEnabled

boolean

Indicates whether clipboard is enabled

autoUpdate

boolean

Indicates whether auto update is enabled

installer

string

Installer information for the client

emailMatch

boolean

Indicates whether the external email matches a Kiteworks email

minVersion

integer

Minimum API version required by this client to operate correctly

links

string[]

HATEOAS links associated with the entity

Request blocked by WAF

Empty response body.

Shell

curl -X GET \
  "https://{instance}.kiteworks.com/rest/clients/me" \
  -H "Authorization: Bearer YOUR_TOKEN"

Python

import requests

url = "https://{instance}.kiteworks.com/rest/clients/me"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())

Responses

{ "id": "mobile_app_ios", "name": "iOS Mobile App", "description": "Company iOS mobile client", "redirect_uri": "https://example.com/callback", "scope": "*", "flag": 0, "flow": 1, "access_token_lifetime": 24, "refresh_token_lifetime": 720, "ask_pin": 1, "pin_timeout": 5, "max_pin_attempts": 5, "type": 2, "touch_id": true, "min_version": 28 }

// Error - No Body

GET/rest/clients/{id}

Get a client

Returns the settings for the specified OAuth client (e.g. an iOS mobile app), including token lifetimes, PIN policy, scope, and OAuth flow configuration.

Parameters

Path Parameters

Required

string

The unique identifier of the client.

Responses

Returns the OAuth client record.

Required

string

Unique Client identifier

name

Required

string

Display name of the client application

description

string

Human-readable description of the client application and its purpose

redirectUri

string

Redirect URL of this client

scope

string

API entities which this client can access

flag

integer

Flags for Client. e.g. NO_CONSENT:1, DISABLED:2, HIDDEN:4, NO_EXPIRY_TOKEN :8

flow

integer

Oauth flow for this client.
e.g. AUTH_CODE:1, CLIENT_CREDENTIAL:2, SIGNATURE:4, REFRESH_TOKEN:8

signatureKey

string

Secret key used to sign requests made by this client

accessTokenLifetime

integer

Life time for access token of client in hours. e.g. 5=5 hours

refreshTokenLifetime

integer

Life time for refresh token of client in hours

whiteList

string

List of applications on the device that the client can call out to

askPin

integer

Indicates whether a PIN should be requested of the user using this client

pinTimeout

integer

Time out for pin of client in minutes

maxPinAttempts

integer

Max attempts that user can try to enter PIN before wipe occurs

type

integer

Client Type. e.g. ACCELLION:1, MOBILE:2, OUTLOOK:4, SYNC:8, IMPORTED:32

touchId

boolean

Indicates whether touch Id is enabled

clipboardEnabled

boolean

Indicates whether clipboard is enabled

autoUpdate

boolean

Indicates whether auto update is enabled

installer

string

Installer information for the client

emailMatch

boolean

Indicates whether the external email matches a Kiteworks email

minVersion

integer

Minimum API version required by this client to operate correctly

links

string[]

HATEOAS links associated with the entity

Request blocked by WAF

Empty response body.

Shell

curl -X GET \
  "https://{instance}.kiteworks.com/rest/clients/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"

Python

import requests

id = "VALUE"  # The unique identifier of the client.

url = f"https://{{instance}}.kiteworks.com/rest/clients/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())

Responses

{ "id": "custom_integration", "name": "Custom Integration", "description": "Third-party integration client", "redirect_uri": "https://integration.example.com/callback", "scope": "files folders", "flag": 0, "flow": 1, "access_token_lifetime": 8, "refresh_token_lifetime": 168, "type": 0, "touch_id": false, "min_version": 28 }

// Error - No Body

PUT/rest/clients/{id}

Update a client

Updates the settings for the specified OAuth client. The fields available for update depend on the client type: custom clients support name, description, redirectUri, accessTokenLifetime, refreshTokenLifetime, scope, and signatureKey; built-in clients support only accessTokenLifetime and refreshTokenLifetime.

Parameters

Path Parameters

Required

string

ID of the client to be updated

Request Body

name

Required

string

Display name of the client application

description

Required

string

Human-readable description of the client application and its purpose

redirectUri

Required

string

Where the server send the code that client can redeem access token.
e.g. https://HOST/rest/callback.html

scope

Required

string

API entities which this client can access

signatureKey

string

Secret key used to sign requests made by this client

accessTokenLifetime

integer

Life time for access token of client in hours. e.g. 5=5 hours

refreshTokenLifetime

integer

Life time for refresh token of client in hours

addLinks

boolean

Indicates whether HATEOAS links should be included in the response

Responses

Returns the updated OAuth client record.

Required

string

Unique Client identifier

name

Required

string

Display name of the client application

description

string

Human-readable description of the client application and its purpose

redirectUri

string

Redirect URL of this client

scope

string

API entities which this client can access

flag

integer

Flags for Client. e.g. NO_CONSENT:1, DISABLED:2, HIDDEN:4, NO_EXPIRY_TOKEN :8

flow

integer

Oauth flow for this client.
e.g. AUTH_CODE:1, CLIENT_CREDENTIAL:2, SIGNATURE:4, REFRESH_TOKEN:8

signatureKey

string

Secret key used to sign requests made by this client

accessTokenLifetime

integer

Life time for access token of client in hours. e.g. 5=5 hours

refreshTokenLifetime

integer

Life time for refresh token of client in hours

whiteList

string

List of applications on the device that the client can call out to

askPin

integer

Indicates whether a PIN should be requested of the user using this client

pinTimeout

integer

Time out for pin of client in minutes

maxPinAttempts

integer

Max attempts that user can try to enter PIN before wipe occurs

type

integer

Client Type. e.g. ACCELLION:1, MOBILE:2, OUTLOOK:4, SYNC:8, IMPORTED:32

touchId

boolean

Indicates whether touch Id is enabled

clipboardEnabled

boolean

Indicates whether clipboard is enabled

autoUpdate

boolean

Indicates whether auto update is enabled

installer

string

Installer information for the client

emailMatch

boolean

Indicates whether the external email matches a Kiteworks email

minVersion

integer

Minimum API version required by this client to operate correctly

links

string[]

HATEOAS links associated with the entity

Forbidden

Possible error codes: ERR_ACCESS_USER

error

Error[]

code

string

Error code

message

string

Error message

Request blocked by WAF

Empty response body.

Shell

curl -X PUT \
  "https://{instance}.kiteworks.com/rest/clients/:id" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "name": "string",
         "description": "string",
         "redirectUri": "string",
         "scope": "string",
         "signatureKey": "string",
         "accessTokenLifetime": 1
       }'

Python

import requests

id = "VALUE"  # ID of the client to be updated

url = f"https://{{instance}}.kiteworks.com/rest/clients/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "name": "string",
  "description": "string",
  "redirectUri": "string",
  "scope": "string",
  "signatureKey": "string",
  "accessTokenLifetime": 1
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())

Responses

{ "id": "custom_integration", "name": "Custom Integration v2", "description": "Updated third-party integration client", "redirect_uri": "https://integration.example.com/callback", "scope": "files folders", "flag": 0, "flow": 1, "access_token_lifetime": 12, "refresh_token_lifetime": 336, "type": 0, "touch_id": false, "min_version": 28 }

{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }

// Error - No Body

DELETE/rest/clients/{id}

Delete a client

Deletes the specified OAuth client. Built-in system clients cannot be deleted.

Parameters

Path Parameters

Required

string

ID of the client to be deleted

Responses

The client was successfully deleted. Returns no content.

Empty response body.

Forbidden

Possible error codes: ERR_ACCESS_USER

error

Error[]

code

string

Error code

message

string

Error message

Request blocked by WAF

Empty response body.

Shell

curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/clients/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"

Python

import requests

id = "VALUE"  # ID of the client to be deleted

url = f"https://{{instance}}.kiteworks.com/rest/clients/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())

Responses

// Request successful - No Body

{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }

// Error - No Body

GET/rest/clients/{id}/scopes

List scopes of a client

Returns the list of API resource scopes the specified client is authorized to access, such as folders, files, members, and comments.

Parameters

Path Parameters

Required

string

ID of the client whose scopes to be retrieved

Query Parameters

mode

Optional

string

Determines the detail level of the response body.

Responses

Client scopes retrieved successfully.

data

string[]

List of API resource scope strings the client is authorized to access (e.g. 'folders/', 'files/').

Request blocked by WAF

Empty response body.

Shell

curl -X GET \
  "https://{instance}.kiteworks.com/rest/clients/:id/scopes" \
  -H "Authorization: Bearer YOUR_TOKEN"

Python

import requests

id = "VALUE"  # ID of the client whose scopes to be retrieved

url = f"https://{{instance}}.kiteworks.com/rest/clients/{id}/scopes"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())

Responses

{ "data": [ "folders/*", "files/*", "members/*", "comments/*" ] }

// Error - No Body

PreviousclientEventLogs

Nextcomments