Connections
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&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
}
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