创建和管理OAuth连接
OAuth连接存储服务或系统(如Slack, Shopify或Zendesk)的OAuth 2.0访问令牌。亚博您可以使用OAuth连接对ZIS流中的API请求进行身份验证。
OAuth连接是ZIS连接服务中的一种连接。有关连接和其他连接类型的详细信息，请参见理解连接．
管理OAuth连接
类来管理OAuth连接OAuth客户和OAuth连接连接API的端点。
在典型的设置中，开发人员首先使用创建OAuth Client端点为ZIS集成中的系统(如Slack)注册OAuth客户端。然后管理员使用私有Zendesk应用程序将集成连接到系统。亚博该应用程序使用OAuth连接端点启动并完成与系统的OAuth流。该应用程序还处理OAuth流所需的任何重定向和管理交互。
当OAuth流完成时，系统向ZIS发送一个OAuth访问令牌。ZIS将此令牌存储在ZIS连接服务中的OAuth连接中。然后，您可以使用该连接对API请求进行身份验证自定义动作在ZIS流中。
有关此设置的示例，请参阅亚博Zendesk应用程序作为管理界面教程系列。
支持的授权类型
OAuth连接支持以下OAuth 2.0授权类型:
- 授权代码
- 客户端凭证
对于使用授权代码流创建的OAuth连接，ZIS还支持刷新令牌授予类型。看到从授权代码流刷新令牌．
不能使用OAuth连接来存储由其他授权类型产生的访问令牌。要存储这些令牌，请使用承载令牌连接代替。
创建OAuth连接
本节包含了在没有Zendesk应用程序的情况下创建OAuth连接的说明。这些说明只使用curl请求和web浏览器。亚博这在构建或测试ZIS集成时非常有用。说明使用相同的API调用和工作流，你会在Zendesk应用程序中使用。亚博
你需要什么?
要完成本节中的步骤，您需要:
已注册的ZIS集成。看到注册集成名称．
用于集成的ZIS OAuth访问令牌。看到获取ZIS OAuth令牌．
注意:这些步骤获取ZIS OAuth令牌不要创建OAuth连接。在ZIS流中，仅使用连接来验证API请求。
为第三方系统创建OAuth连接
要为第三方系统创建OAuth连接，首先需要在系统中创建OAuth客户端。然后需要在ZIS中注册客户端。在OAuth流期间，ZIS使用客户机将数据传递给系统。
注册OAuth客户端后，您可以使用OAuth Connections端点启动并完成OAuth流。启动和完成流程的步骤因授权类型而异。
为Zendesk创建OAuth连接的步骤与其他系统不同。亚博看到为Zendesk创建OAuth连接亚博．
注册OAuth客户端
首先，创建并注册一个OAuth客户端。
在第三方系统中创建OAuth客户端。这些步骤因系统而异。将客户端的回调URL设置为“https://”
zis.亚博zendesk.com/api/services/zis/connections/oauth/callback”。完成后，系统应该提供客户机id和密钥。 做一个创建OAuth Client请求在ZIS中注册系统的OAuth客户端。
例如，下面的请求为Slack创建一个OAuth客户端。客户端命名为“slack”。客户端使用默认值
grant_type“authorization_code”。curl -X POST https://{subdomain}.亚博zendesk.com/api/services/zis/connections/oauth/clients/{integration} \-H "Authorization: Bearer {access_token}" \-H "Content-type: application/json" \- d”{“名称”:“松”,:“client_id client_id”,:“client_secret client_secret”,:“grant_type authorization_code”,:“default_scopes聊天:写”,“auth_url”:“https://slack.com/oauth/v2/authorize”,“token_url”:“https://slack.com/api/oauth.v2.access”} '作为另一个例子，下面的请求为Spotify创建一个OAuth客户端。客户端命名为“spotify”。客户端使用默认值
grant_type“client_credentials”。curl -X POST https://{subdomain}.亚博zendesk.com/api/services/zis/connections/oauth/clients/{integration} \-H "Authorization: Bearer {access_token}" \-H "Content-type: application/json" \- d”{“名称”:“spotify”,:“client_id client_id”,:“client_secret client_secret”,:“grant_type client_credentials”,“token_url”:“https://accounts.spotify.com/api/token”} '
启动授权代码流
在注册相关的OAuth客户端之后，您可以使用OAuth Connections端点使用授权码授予类型启动带有第三方系统的OAuth流。
授权代码流需要Zendesk管理员的直接交互。亚博管理员必须通过OAuth授权页面批准对第三方系统的访问。
做一个启动OAuth Flow请求用系统启动OAuth流。为系统中的已注册OAuth客户端指定名称
oauth_client_name．例如，下面的请求创建一个名为“slack”的OAuth连接。该连接使用“slack”OAuth客户端。重要的是:不要使用
名字“zen亚博desk”。此名称保留用于到Zendesk的OAuth连接。亚博如果您正在创建OAuth连接，而不使用Zendesk应用程序，请保留亚博
origin_oauth_redirect_url值为“https”: / / example.local”。 通过…
access_type设置OAuth流授权请求中“offline”的查询参数allow_offline_access“真正的”。一些第三方系统，如谷歌api，要求此设置让ZIS或其他应用程序在没有用户在场的情况下刷新访问令牌。curl -X POST https://{subdomain}.亚博zendesk.com/api/services/zis/connections/oauth/start/{integration} \-H "Authorization: Bearer {access_token}" \-H 'content-type: application/json' \- d”{“名称”:“松”,“oauth_client_name”:“松”,:“grant_type authorization_code”,“origin_oauth_redirect_url”:“https://example.local”,:“permission_scopes聊天:写”,“allow_offline_access”:假的} '请求返回一个重定向URL。
{“redirect_url”：“https://zis.亚博zendesk.com/api/services/zis/connections/oauth/start_redirect?flow_token=xyz”}在一个典型的设置中，Zendesk应用程序打开管亚博理员的重定向URL。如果你在没有应用程序的情况下创建OAuth连接，请在web浏览器中打开重定向URL。该URL将您重定向到系统的OAuth授权页面。完成页面上的授权步骤。
授权后，系统会将您重定向到
origin_oauth_redirect_url启动OAuth流请求。URL现在包含一个verification_token查询参数。该参数包含系统的OAuth验证码。如果你用了
origin_oauth_redirect_url“https://的例子。，则URL返回浏览器错误。这是预期的，并且不会干扰连接的创建。您可以安全地关闭浏览器选项卡。 
在浏览器之外，ZIS生成一个授权码请求对系统。如果请求成功，系统返回一个访问令牌响应．
ZIS将响应的访问令牌存储在OAuth连接中。如果提供，ZIS还将在连接中存储响应的过期时间和刷新令牌。该连接使用
名字您在启动OAuth流请求中指定的。作为可选步骤，使用显示OAuth连接请求。下面的请求获取名为“slack”的OAuth连接。
旋度https://{subdomain}.zen亚博desk.com/api/services/zis/connections/{integration}?name=slack \-H "Authorization: Bearer {access_token}"响应包含有关连接的信息，包括其
access_token．{“uuid”：“* * * uuid * * *”，“名称”：“松弛”，“亚博zendesk_account_id”：12345678，“集成”：“example_亚博zendesk_to_slack”，“permission_scope”：“聊天:写”，“access_token”：“* * * * * *访问令牌”，“token_type”：“机器人”，“refresh_token”：＂＂，“token_expiry”：“0001 - 01 - 01 t00:00:00z”，“oauth_access_token_response_body”：＂＂，“oauth_url_subdomain”：“例子”，“created_by”：“1234567890123”，“created_at”：“2099 - 05 - 16 - t15:33:19z”}
从授权代码流刷新令牌
如果使用授权码流创建的OAuth连接包含刷新令牌，则ZIS可以使用刷新令牌流自动刷新连接的访问令牌。启用自动刷新。
集
allow_offline_access到连接中的“true”启动OAuth Flow请求。有些系统需要此设置来在没有用户在场的情况下刷新访问令牌。确保系统的访问令牌响应包括非空
expires_in和refresh_token值。对于不提供这些值的系统，ZIS无法刷新访问令牌。
的访问令牌强制刷新OAuth连接的访问令牌刷新OAuth Token请求。例如，下面的请求强制刷新名为“hubspot”的连接。
旋度https://{subdomain}.zen亚博desk.com/api/services/zis/connections/refresh/{integration}?name=hubspot \-H "Authorization: Bearer {access_token}"
启动客户机凭据流
在注册相关的OAuth客户端之后，您可以使用OAuth Connections端点使用客户端凭证授予类型启动带有第三方系统的OAuth流。
客户端凭证流通常用于机器对机器身份验证。该流程不需要Zendesk管理员的交互或批准。亚博
做一个启动OAuth Flow请求用系统启动OAuth流。为系统中的已注册OAuth客户端指定名称
oauth_client_name．例如，下面的请求创建一个名为“spotify”的OAuth连接。该连接使用“spotify”OAuth客户端。重要的是:不要使用
名字“zen亚博desk”。此名称保留用于到Zendesk的OAuth连接。亚博curl -X POST https://{subdomain}.亚博zendesk.com/api/services/zis/connections/oauth/start/{integration} \-H "Authorization: Bearer {access_token}" \-H 'content-type: application/json' \- d”{“名称”:“spotify”,:“oauth_client_name spotify”,:“grant_type client_credentials”} '的URL交易所验证码端点。
{“redirect_url”：“https://{子域名}.zendes亚博k.com/api/services/zis/connections/oauth/access_codes/{集成}? verification_code = xyz”}使用URL创建一个交易所验证码请求。将URL用引号括起来以转义任何特殊字符。
Curl "https://{subdomain}.亚博zendesk.com/api/services/zis/connections/oauth/access_codes/{integration}?verification_code=xyz" \-H "Authorization: Bearer {access_token}"响应包含有关OAuth连接的详细信息，包括其访问令牌。例子:
{“uuid”：“* * * uuid * * *”，“亚博zendesk_account_id”：12345678，“集成”：“集成”，“名称”：“spotify”，“permission_scope”：＂＂，“access_token”：“* * * * * *访问令牌”，“token_type”：“持票人”，“refresh_token”：＂＂，“token_expiry”：“2099 - 05 - 06 - t18:37:39z”，“oauth_access_token_response_body”：＂＂，“origin_oauth_redirect_url”：＂＂，“raw_callback_params”：＂＂，“created_by”：“1234567890123”}
从客户端凭证流更新令牌
使用客户端凭证流创建的OAuth连接可能包括token_expiry日期。当令牌过期时，ZIS通过使用相同的OAuth客户端完成客户端凭证流来自动获取新的访问令牌。
的访问令牌强制更新OAuth连接的访问令牌刷新OAuth Token请求。例如，下面的请求强制更新名为“spotify”的连接。
旋度https://{subdomain}.zen亚博desk.com/api/services/zis/connections/refresh/{integration}?name=spotify \-H "Authorization: Bearer {access_token}"
为Zendesk创建OAuth连接亚博
当您注册一个ZIS集成时，请求会自动在ZIS中创建一个Zendesk OAuth客户端。亚博这个客户端名为“zendesk”。亚博您可以使用该客户端启动OAuth流。OAuth流使用授权码授予类型。生成的Zendesk访问令牌亚博不会过期或使用刷新令牌。
做一个启动OAuth Flow请求使用Zendesk启动OAuth流。亚博在请求中，指定a
名字和oauth_client_name“zen亚博desk”。指定您的Zendesk子域亚博oauth_url_subdomain．如果你正在创建一个没有Zendesk应用程序的连接，离开亚博
origin_oauth_redirect_url为“https:/ / example.local”。 curl -X POST https://{subdomain}.亚博zendesk.com/api/services/zis/connections/oauth/start/{integration} \-H "Authorization: Bearer {access_token}" \-H 'content-type: application/json' \- d”{“名称”:“zen亚博desk”,:“oauth_client_name ze亚博ndesk”,:“oauth_url_subdomain ZE亚博NDESK_SUBDOMAIN”,“origin_oauth_redirect_url”:“https://example.local”,permission_scopes:读写;“allow_offline_access”:假的} '请求返回一个重定向URL。
{“redirect_url”：“https://zis.亚博zendesk.com/api/services/zis/connections/oauth/start_redirect?flow_token=xyz”}在一个典型的设置中，Zendesk应用程序打开管亚博理员的重定向URL。如果你在没有应用程序的情况下创建连接，请在web浏览器中打开重定向URL。
如果你还没有登录到Zendesk，这个URL会将你重定向到Zendes亚博k登录页面。使用此页登录到Zendesk。亚博
登录后，Zendesk会将您重定向到亚博
origin_oauth_redirect_url启动OAuth流请求。URL现在包含一个verification_token查询参数。该参数包含Zendesk的OAuth验证码。亚博如果你用了
origin_oauth_redirect_url“https: / /例子。，则URL返回浏览器错误。这是预期的，并且不会干扰连接的创建。您可以安全地关闭浏览器选项卡。 在浏览器之外，ZIS将验证码交换为Zendesk OAuth访问令牌。亚博然后，ZIS将令牌存储在“zendesk”OAuth连接中。亚博
作为可选步骤，使用亚博显示OAuth连接请求。
旋度https://{subdomain}.zen亚博desk.com/api/services/zis/connections/{integration}?name=zendesk \-H "Authorization: Bearer {access_token}"响应包含有关连接的信息，包括其
access_token．{“uuid”：“* * * uuid * * *”，“名称”：“亚博zendesk”，“亚博zendesk_account_id”：12345678，“集成”：“example_亚博zendesk_to_slack”，“permission_scope”：“读写“，“access_token”：“* * * * * *访问令牌”，“token_type”：“持票人”，“refresh_token”：＂＂，“token_expiry”：“0001 - 01 - 01 t00:00:00z”，“oauth_access_token_response_body”：＂＂，“oauth_url_subdomain”：“例子”，“created_by”：“1234567890123”，“created_at”：“2099 - 05 - 16 - t15:33:19z”}
使用OAuth连接验证API请求
要使用OAuth连接对API请求进行身份验证，请参见使用连接对ZIS流中的API请求进行身份验证．
之前，您也可以使用.connections美元。{oauth_connection_name} .access_token参考路径在操作状态下访问OAuth连接的访问令牌。此引用路径已弃用，可能会在将来的版本中删除。
正在更新OAuth连接
若要更新或替换现有的OAuth连接，请执行启动OAuth Flow请求使用相同的连接名字．然后使用与创建连接时相同的步骤完成OAuth流。更新OAuth连接不会改变OAuth客户端。
例如，下面的请求更新一个名为“slack”的现有OAuth连接。
curl -X POST https://{subdomain}.亚博zendesk.com/api/services/zis/connections/oauth/start/{integration} \-H "Authorization: Bearer {access_token}" \-H 'content-type: application/json' \- d”{“名称”:“松”,“oauth_client_name”:“松”,“origin_oauth_redirect_url”:“https://example.local”,“permission_scopes”:“聊天:写:机器人”,“allow_offline_access”:假的} '