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"
    ...
  }
}