OAuth Clients

JSON Format

OAuth Clients are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
company string false false The company name displayed when users are asked to grant access to your application.
created_at string true false The time the client was created
description string false false A short description of your client that is displayed to users when they are considering approving access to your application
global boolean true false Whether this client is globally accessible. Learn more
id integer true false Automatically assigned upon creation
identifier string false true The unique identifier for this client
logo_url string true false The API logo url of this record
name string false true The name of this client
redirect_uri array false false An array of the valid redirect URIs for this client
secret string true false The client secret. Generated automatically on creation and returned in full only at that time
updated_at string true false The time of the last update of the client
url string true false The API url of this record
user_id integer false true The id of the admin who created the client
Example
{
  "company": "Zendesk",
  "created_at": "2009-05-13T00:07:08Z",
  "description": "Zendesk Test Client",
  "id": 1,
  "identifier": "test_client",
  "name": "My Test Client",
  "redirect_uri": [
    "https://example.com/callback"
  ],
  "secret": "af3t24tfj34h43s...",
  "updated_at": "2011-07-22T00:11:12Z",
  "url": "https://example.zendesk.com/api/v2/clients/1.json",
  "user_id": 29
}

List Clients

  • GET /api/v2/oauth/clients
  • 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 OK

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

Create Client

  • POST /api/v2/oauth/clients
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": {
    "company": "Zendesk",
    "created_at": "2009-05-13T00:07:08Z",
    "description": "Zendesk Test Client",
    "id": 223443,
    "identifier": "test_client",
    "name": "Test Client",
    "redirect_uri": [
      "https://example.com/callback"
    ],
    "secret": "af3t24tfj34h43s...",
    "updated_at": "2011-07-22T00:11:12Z",
    "url": "https://example.zendesk.com/api/v2/clients/223443.json",
    "user_id": 29
  }
}

Show Client

  • GET /api/v2/oauth/clients/{oauth_client_id}
Allowed for
  • Admins
Parameters
Name Type In Required Description
oauth_client_id integer Path true The ID of the OAuth client
Using curl
curl https://{subdomain}.zendesk.com/api/v2/oauth/clients/{oauth_client_id}.json \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

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

Update Client

  • PUT /api/v2/oauth/clients/{oauth_client_id}
Allowed for
  • Admins
Parameters
Name Type In Required Description
oauth_client_id integer Path true The ID of the OAuth client
Using curl
curl https://{subdomain}.zendesk.com/api/v2/oauth/clients/{oauth_client_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 OK

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

Delete Client

  • DELETE /api/v2/oauth/clients/{oauth_client_id}
Allowed for
  • Admins
Parameters
Name Type In Required Description
oauth_client_id integer Path true The ID of the OAuth client
Using curl
curl https://{subdomain}.zendesk.com/api/v2/oauth/clients/{oauth_client_id}.json \
  -X DELETE -v -u {email_address}:{password}
Example Response
Status 204 No Content

Generate Secret

  • PUT /api/v2/oauth/clients/{oauth_client_id}/generate_secret
Allowed for
  • Admins
Parameters
Name Type In Required Description
oauth_client_id integer Path true The ID of the OAuth client
Using curl
curl https://{subdomain}.zendesk.com/api/v2/oauth/clients/{oauth_client_id}/generate_secret.json \
  -X PUT -v -u {email_address}:{password}
Example Response
Status 200 OK

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