OAuth Connections
Stores and manages OAuth access tokens for an integration. See Creating and managing OAuth connections.
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 | false | false | The name of the integration |
name | string | false | false | Name used to uniquely identify the connection. See Connection names |
oauth_access_token_response_body | string | true | false | The response from the OAuth provider when getting an access token |
oauth_url_subdomain | string | false | false | Subdomain is used to interpolate the subdomain placeholder in the OAuth provider's authorization or token URL |
permission_scope | string | false | 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_oauth_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_oauth_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_oauth_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_oauth_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_oauth_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"
}
]
}