OAuth Connections

The OAuth Connections API is used to store and manage an OAuth2 token and to start and manage an OAuth authorization code grant type flow for an integration.

JSON Format

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

Name	Type	Read-only	Mandatory	Description
access_token	string	true	false	The OAuth access token
created_by	string	true	false	User who created the connection
integration	string	true	false	The name of the integration
name	string	true	false	Name used to uniquely identify a connection. For example, an OAuth token scoped by an integration key
oauth_access_token_response_body	string	true	false	The response from the OAuth provider when getting an access token
oauth_url_subdomain	string	true	false	Subdomain is used to interpolate the subdomain placeholder in the OAuth provider's authorization or token URL
permission_scope	string	true	false	The space delimited string to list the desired OAuth permissions for the OAuth flow
refresh_token	string	true	false	The OAuth refresh token
token_expiry	string	true	false	The expiry date time of the access token. Format of YYYY-MM-DDThh:mm:ssZ
token_type	string	true	false	The type of token. For example, "bearer"
uuid	string	true	false	The UUID of the connection
zendesk_account_id	integer	true	false	The Zendesk account ID

Start OAuth Flow

• POST /api/services/zis/connections/oauth/start/{integration}

Starts the OAuth flow for the client.

Authentication

You can authorize requests using a ZIS OAuth access token. A Zendesk app can also authorize requests to this endpoint using an admin's browser session. See Making API requests from a Zendesk app.

Parameters

Name	Type	In	Required	Description
integration	string	Path	true	Name of the integration

Example Body

{
  "allow_offline_access": true,
  "grant_type": "authorization_code",
  "name": "my_flow",
  "oauth_client_name": "my_oauth_client_name",
  "oauth_client_uuid": "9c81f444-4beb-4ba7-9bcc-6b2d068e7ade",
  "oauth_url_subdomain": "foobar",
  "origin_oauth_redirect_url": "https://client.int/callback",
  "permission_scopes": "read write"
}

Using cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/start/{integration} \
-H "Authorization: Bearer {access_token}" \
-X POST \
-H 'content-type: application/json' \
-d '{
  "allow_offline_access": true,
  "grant_type": "authorization_code",
  "name": "my_flow",
  "oauth_client_name": "my_oauth_client_name",
  "oauth_client_uuid": "9c81f444-4beb-4ba7-9bcc-6b2d068e7ade",
  "oauth_url_subdomain": "foobar",
  "origin_oauth_redirect_url": "https://client.int/callback",
  "permission_scopes": "read write"
}'

Example Response(s)

200 OK

Status 200 OK

{
  "redirect_url": "https://foobar.zendesk.com/api/services/zis/connections/oauth/start_redirect?flow_token=xyz"
}

401 Unauthorized

Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1200",
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

403 Forbidden

Status 403 Forbidden

{
  "errors": [
    {
      "code": "1200",
      "detail": "Forbidden",
      "status": "403"
    }
  ]
}

404 Not Found

Status 404 Not Found

{
  "errors": [
    {
      "code": "1302",
      "detail": "Not found",
      "status": "404"
    }
  ]
}

422 Unprocessable Entity

Status 422 Unprocessable Entity

{
  "errors": [
    {
      "code": "1303",
      "detail": "Invalid value for: Integration. Desc: Integration cannot be nil",
      "status": "422"
    }
  ]
}

429 Too Many Requests

Status 429 Too Many Requests

{
  "errors": [
    {
      "code": "1300",
      "detail": "Too many requests",
      "status": "429"
    }
  ]
}

Start OAuth Redirect

• GET /api/services/zis/connections/oauth/start_redirect?flow_token={flow_token}

When making an HTTPs request to Start OAuth Flow, this endpoint is returned in redirect_url in the response.

Parameters

Name	Type	In	Required	Description
flow_token	string	Query	true	The token that is part of the redirect_url response from the /oauth/start/{integration} endpoint

Using cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/start_redirect?flow_token={flow_token}

Example Response(s)

307 Temporary Redirect

Status 307 Temporary Redirect

400 Bad Request

Status 400 Bad Request

{
  "errors": [
    {
      "code": "1301",
      "detail": "Invalid request",
      "status": "400"
    }
  ]
}

OAuth Token

• POST /api/services/zis/connections/oauth/tokens/{integration}

Returns a proxy for the Zendesk OAuth Token URL. For more information on the Zendesk OAuth flow, see Using OAuth authentication with your application.

Parameters

Name	Type	In	Required	Description
integration	string	Path	true	Name of the integration

Example Body

{
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "code": "LgwEzL8CA3aRA35r5QYfRbjjMa3Iacsk1CvwcRsnM",
  "grant_type": "authorization_code",
  "redirect_uri": "https://client.int/callback",
  "scope": "read write"
}

Using cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/tokens/{integration} \
-X POST \
-H 'content-type: application/json' \
-d '{
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "code": "LgwEzL8CA3aRA35r5QYfRbjjMa3Iacsk1CvwcRsnM",
  "grant_type": "authorization_code",
  "redirect_uri": "https://client.int/callback",
  "scope": "read write"
}'

Example Response(s)

200 OK

Status 200 OK

{
  "access_token": "ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC-ThYWDqY2_M5w==",
  "scope": "read write",
  "token_type": "bearer"
}

400 Bad Request

Status 400 Bad Request

{
  "errors": [
    {
      "code": "1301",
      "detail": "Invalid request",
      "status": "400"
    }
  ]
}

401 Unauthorized

Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1200",
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

403 Forbidden

Status 403 Forbidden

{
  "errors": [
    {
      "code": "1200",
      "detail": "Forbidden",
      "status": "403"
    }
  ]
}

422 Unprocessable Entity

Status 422 Unprocessable Entity

{
  "errors": [
    {
      "code": "1303",
      "detail": "Invalid value for: Integration. Desc: Integration cannot be nil",
      "status": "422"
    }
  ]
}

Exchange Verification Code

• GET /api/services/zis/connections/oauth/access_codes/{integration}?verification_code={verification_code}

Returns an access code and connection UUID when the verification code is provided.

Authentication

You can authorize requests using a ZIS OAuth access token. A Zendesk app can also authorize requests to this endpoint using an admin's browser session. See Making API requests from a Zendesk app.

Parameters

Name	Type	In	Required	Description
verification_code	string	Query	true	The verification code returned from the authorization flow
integration	string	Path	true	Name of the integration

Using cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/oauth/access_codes/{integration}?verification_code={verification_code} \
-H "Authorization: Bearer {access_token}"

Example Response(s)

200 OK

Status 200 OK

{
  "access_token": "ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC-ThYWDqY2_M5w==",
  "created_by": "test_user",
  "integration": "my_integration",
  "oauth_access_token_response_body": "{\"access_token\":\"ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC\"}",
  "origin_oauth_redirect_url": "https://client.int/callback",
  "permission_scope": "read write",
  "raw_callback_params": "code=aPrx.f3G28C1ueiVxd.Skd2w.u5bioOnuzTNDdT81IaImk7PKmXXHAfVBtYu5rK.Yh.lDL4jsA&state=CC5j68_SRVA5pSBbDkMq2sa4d36NyibXf12_Hf2POkk",
  "refresh_token": "cs95Xaw_F5PKcxO4fQ9bZKklHKncdkXIc9qGrvktPt2elg==",
  "token_expiry": "2021-10-01T12:44:22Z",
  "token_type": "bearer",
  "uuid": "ac10a230-0c43-45f8-b221-9e085ce90418",
  "zendesk_account_id": 123456
}

400 Bad Request

Status 400 Bad Request

{
  "errors": [
    {
      "code": "1301",
      "detail": "Invalid request",
      "status": "400"
    }
  ]
}

401 Unauthorized

Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1200",
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

Refresh OAuth Token

• GET /api/services/zis/connections/refresh/{integration}

Refreshes an OAuth token.

Parameters

Name	Type	In	Required	Description
name	string	Query	false	Name of connection. Specify either "uuid" or "name"
uuid	string	Query	false	UUID of connection. Specify either "uuid" or "name"
integration	string	Path	true	Name of the integration

Using cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/refresh/{integration}?uuid={uuid} \
-H "Authorization: Bearer {access_token}"

Using cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/refresh/{integration}?name={name} \
-H "Authorization: Bearer {access_token}"

Example Response(s)

200 OK

Status 200 OK

{
  "access_token": "ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC-ThYWDqY2_M5w==",
  "created_by": "test_user",
  "integration": "my_integration",
  "name": "my_connection",
  "oauth_access_token_response_body": "{\"access_token\":\"ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC\"}",
  "oauth_url_subdomain": "foobar",
  "permission_scope": "read write",
  "refresh_token": "cs95Xaw_F5PKcxO4fQ9bZKklHKncdkXIc9qGrvktPt2elg==",
  "token_expiry": "2021-10-01T12:44:22Z",
  "token_type": "bearer",
  "uuid": "ac10a230-0c43-45f8-b221-9e085ce90418",
  "zendesk_account_id": 123456
}

400 Bad Request

Status 400 Bad Request

{
  "errors": [
    {
      "code": "1301",
      "detail": "Invalid request",
      "status": "400"
    }
  ]
}

401 Unauthorized

Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1200",
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

403 Forbidden

Status 403 Forbidden

{
  "errors": [
    {
      "code": "1200",
      "detail": "Forbidden",
      "status": "403"
    }
  ]
}

422 Unprocessable Entity

Status 422 Unprocessable Entity

{
  "errors": [
    {
      "code": "1303",
      "detail": "Invalid value for: Integration. Desc: Integration cannot be nil",
      "status": "422"
    }
  ]
}

Show OAuth Connection

• GET /api/services/zis/connections/{integration}

Returns connection details for an integration.

Authentication

You can authorize requests using a ZIS OAuth access token. A Zendesk app can also authorize requests to this endpoint using an admin's browser session. See Making API requests from a Zendesk app.

Parameters

Name	Type	In	Required	Description
name	string	Query	false	Name of connection. Specify either "uuid" or "name"
uuid	string	Query	false	UUID of connection. Specify either "uuid" or "name"
integration	string	Path	true	Name of the integration

Using cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/{integration}?uuid={uuid} \
-H "Authorization: Bearer {access_token}"

Using cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/{integration}?name={name} \
-H "Authorization: Bearer {access_token}"

Example Response(s)

200 OK

Status 200 OK

{
  "access_token": "ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC-ThYWDqY2_M5w==",
  "created_by": "test_user",
  "integration": "my_integration",
  "name": "my_connection",
  "oauth_access_token_response_body": "{\"access_token\":\"ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC\"}",
  "oauth_url_subdomain": "foobar",
  "permission_scope": "read write",
  "refresh_token": "cs95Xaw_F5PKcxO4fQ9bZKklHKncdkXIc9qGrvktPt2elg==",
  "token_expiry": "2021-10-01T12:44:22Z",
  "token_type": "bearer",
  "uuid": "ac10a230-0c43-45f8-b221-9e085ce90418",
  "zendesk_account_id": 123456
}

400 Bad Request

Status 400 Bad Request

{
  "errors": [
    {
      "code": "1301",
      "detail": "Invalid request",
      "status": "400"
    }
  ]
}

401 Unauthorized

Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1200",
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

403 Forbidden

Status 403 Forbidden

{
  "errors": [
    {
      "code": "1200",
      "detail": "Forbidden",
      "status": "403"
    }
  ]
}

422 Unprocessable Entity

Status 422 Unprocessable Entity

{
  "errors": [
    {
      "code": "1303",
      "detail": "Invalid value for: Integration. Desc: Integration cannot be nil",
      "status": "422"
    }
  ]
}

Show OAuth Connections

• GET /api/services/zis/integrations/{integration}/connections?named={named}

Returns a list of Connections for the integration. The support is now limited to ?named=true to return only the named connections.

Authentication

You can authorize requests using a ZIS OAuth access token. A Zendesk app can also authorize requests to this endpoint using an admin's browser session. See Making API requests from a Zendesk app.

Parameters

Name	Type	In	Required	Description
named	boolean	Query	true	Boolean to return named connections only
integration	string	Path	true	Name of the integration

Using cURL

curl https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/connections?named=true \
-H "Authorization: Bearer {access_token}"

Example Response(s)

200 OK

Status 200 OK

{
  "connections": [
    {
      "access_token": "ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC-ThYWDqY2_M5w==",
      "created_by": "test_user",
      "integration": "my_integration",
      "name": "my_connection",
      "oauth_access_token_response_body": "{\"access_token\":\"ps55XW1CbNj_hKnzwJU3yc968SL39yh3C3Okn1fpC\"}",
      "oauth_url_subdomain": "foobar",
      "permission_scope": "read write",
      "refresh_token": "cs95Xaw_F5PKcxO4fQ9bZKklHKncdkXIc9qGrvktPt2elg==",
      "token_expiry": "2021-10-01T12:44:22Z",
      "token_type": "bearer",
      "uuid": "ac10a230-0c43-45f8-b221-9e085ce90418",
      "zendesk_account_id": 123456
    }
  ]
}

400 Bad Request

Status 400 Bad Request

{
  "errors": [
    {
      "code": "1301",
      "detail": "Invalid request",
      "status": "400"
    }
  ]
}

401 Unauthorized

Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1200",
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

403 Forbidden

Status 403 Forbidden

{
  "errors": [
    {
      "code": "1200",
      "detail": "Forbidden",
      "status": "403"
    }
  ]
}

422 Unprocessable Entity

Status 422 Unprocessable Entity

{
  "errors": [
    {
      "code": "1303",
      "detail": "Invalid value for: Integration. Desc: Integration cannot be nil",
      "status": "422"
    }
  ]
}

Update Connection

• PATCH /api/services/zis/connections/{integration}?uuid={uuid}

Updates connection details.

Parameters

Name	Type	In	Required	Description
uuid	string	Query	true	UUID of the connection
integration	string	Path	true	Name of the integration

Example Body

{
  "name": "my_connection"
}

Using cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/{integration}?uuid={uuid} \
-H "Authorization: Bearer {access_token}" \
-X PATCH \
-H 'content-type: application/json' \
-d '{
  "name": "my_connection"
}'

Example Response(s)

204 No Content

Status 204 No Content

401 Unauthorized

Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1200",
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

403 Forbidden

Status 403 Forbidden

{
  "errors": [
    {
      "code": "1200",
      "detail": "Forbidden",
      "status": "403"
    }
  ]
}

404 Not Found

Status 404 Not Found

{
  "errors": [
    {
      "code": "1302",
      "detail": "Not found",
      "status": "404"
    }
  ]
}

422 Unprocessable Entity

Status 422 Unprocessable Entity

{
  "errors": [
    {
      "code": "1303",
      "detail": "Invalid value for: Integration. Desc: Integration cannot be nil",
      "status": "422"
    }
  ]
}

429 Too Many Requests

Status 429 Too Many Requests

{
  "errors": [
    {
      "code": "1300",
      "detail": "Too many requests",
      "status": "429"
    }
  ]
}

Delete Connection

• DELETE /api/services/zis/connections/{integration}

Deletes the authorization token stored in the ZIS Connection Service.

Parameters

Name	Type	In	Required	Description
name	string	Query	false	Name of connection. Specify either "uuid" or "name"
uuid	string	Query	false	UUID of connection. Specify either "uuid" or "name"
integration	string	Path	true	Name of the integration

Using cURL

curl https://{subdomain}.zendesk.com/api/services/zis/connections/{integration}?uuid={uuid} \
-H "Authorization: Bearer {access_token}" \
-X DELETE

Using cURL

curl curl https://{subdomain}.zendesk.com/api/services/zis/connections/{integration}?name={name} \
-H "Authorization: Bearer {access_token}" \
-X DELETE

Example Response(s)

204 No Content

Status 204 No Content

401 Unauthorized

Status 401 Unauthorized

{
  "errors": [
    {
      "code": "1200",
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

403 Forbidden

Status 403 Forbidden

{
  "errors": [
    {
      "code": "1200",
      "detail": "Forbidden",
      "status": "403"
    }
  ]
}

404 Not Found

Status 404 Not Found

{
  "errors": [
    {
      "code": "1302",
      "detail": "Not found",
      "status": "404"
    }
  ]
}