OAuth Clients

JSON Format

OAuth2 clients are represented with the following attributes:

Name	Type	Read-only	Mandatory	Comment
id	integer	yes	no	Automatically assigned upon creation
name	string	no	yes	The name of this client
identifier	string	no	yes	The unique identifier for this client
secret	string	yes	no	The client secret. Generated automatically on creation and returned in full only at that time.
company	string	no	no	Choose a company name to display when users are asked to approve access to your application. The name will help users understand who they are granting access to.
description	string	no	no	A short description of your client that is displayed to users when they are considering approving access to your application.
redirect_uri	array	no	no	An array of the valid redirect URIs for this client
user_id	integer	no	yes	The id of the admin who created the client
global	boolean	yes	no	Whether this client is globally accessible. Learn more
url	string	yes	no	The API url of this record
logo_url	string	yes	no	The API logo url of this record
created_at	date	yes	no	The time the client was created
updated_at	date	yes	no	The time of the last update of the client

Example

{
  "id":           1,
  "name":         "My Test Client",
  "identifier":   "test_client",
  "company":      "Zendesk",
  "description":  "Zendesk Test Client",
  "secret":       "af3t24tfj34h43s...",
  "redirect_uri": ["https://example.com/callback"],
  "user_id":      29,
  "url":          "https://example.zendesk.com/api/v2/clients/1.json",
  "created_at":   "2009-05-13T00:07:08Z",
  "updated_at":   "2011-07-22T00:11:12Z"
}

List Clients

GET /api/v2/oauth/clients.json
GET /api/v2/users/me/oauth/clients.json

Allowed For

Admins

Using curl

curl https://{subdomain}.zendesk.com/api/v2/oauth/clients.json \
  -v -u {email_address}:{password}

Example Response

Status: 200

{
  "clients": [
    {
      "id": 223443,
      "name": "Stats Widget",
      ...
    },
    {
      "id": 8678530,
      "name": "Zendesk Mobile",
      ...
    }
  ]
}

Show Client

GET /api/v2/oauth/clients/{id}.json

Allowed For

Admins

Using curl

curl https://{subdomain}.zendesk.com/api/v2/oauth/clients/{id}.json \
  -v -u {email_address}:{password}

Example Response

Status: 200

{
  "client": {
    "id": 223443,
    "name": "Stats Widget",
    ...
  }
}

Create Client

POST /api/v2/oauth/clients.json

Allowed For

Admins

Using curl

curl https://{subdomain}.zendesk.com/api/v2/oauth/clients.json \
  -X POST -H "Content-Type: application/json" \
  -d '{"client": {"name": "Test Client", "identifier": "unique_id"}}'
  -v -u {email_address}:{password}

Example Response

Status: 201 Created

{
  "client": {
    "id": 223443,
    "name": "Test Client",
    "secret": "full, generated secret"
    ...
  }
}

Update Client

PUT /api/v2/oauth/clients/{id}.json

Allowed For

Admins

Using curl

curl https://{subdomain}.zendesk.com/api/v2/oauth/clients/{id}.json \
  -X PUT -H "Content-Type: application/json" \
  -d '{"client": {"name": "My New OAuth2 Client"}}'
  -v -u {email_address}:{password}

Example Response

Status: 200

{
  "client": {
    "id": 223443,
    "name": "My New OAuth2 Client",
    "secret": "truncated, existing secret"
    ...
  }
}

Delete Client

DELETE /api/v2/oauth/clients/{id}.json

Allowed For

Admins

Using curl

curl https://{subdomain}.zendesk.com/api/v2/oauth/clients/{id}.json \
  -X DELETE -v -u {email_address}:{password}

Example Response

Status: 204 No Content

Generate Secret

PUT /api/v2/oauth/clients/{id}/generate_secret.json

Allowed For

Admins

Using curl

curl https://{subdomain}.zendesk.com/api/v2/oauth/clients/{id}/generate_secret.json \
  -X PUT -v -u {email_address}:{password}

Example Response

Status: 200 OK

{
  "client": {
    "id": 223443,
    "name": "Test Client",
    "secret": "full, generated secret"
    ...
  }
}