The 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

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.

Parameters

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

Example Body

{  "allow_offline_access": true,  "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,  "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

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

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

Status 307 Temporary Redirect

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

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

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.

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

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\u0026state=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}

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

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}

Show Connection

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

Returns connection details for an integration.

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

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}

Show 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.

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

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    }  ]}

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

Status 204 No Content

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

Status 204 No Content