Zoho crm Logo

授权请求

要使用Zoho CRM API,用户必须使用访问令牌对应用程序进行身份验证,以便代表他们进行API调用。

访问令牌必须从授权令牌(授权代码)中获取。Zoho CRM API使用授权代码授权类型来提供对受保护资源的访问。

注意

特定组织授权令牌(授权码)

  • 用户可以选择只授予应用程序对特定组织的访问权限(无论是在CRM的生产环境、沙箱环境还是开发者环境中)。因此,为用户生成的访问和刷新令牌在一个环境中变为特定于组织的。例如,应用程序所有者不能使用为生产环境中的组织生成的令牌来对沙箱或开发者账户中的组织进行API调用。
  • 如果你的基于web的应用程序在多个环境中有多个组织(例如,生产环境中有一个,沙箱和开发者环境中各有两个),用户将被允许选择需要生成授权令牌的组织。
    相反,如果你的应用程序只有一个组织(例如,生产环境中有一个,沙箱或开发者环境中没有),系统会自动为其生成授权令牌,无需询问任何选择。
  • 对于自我客户,系统会呈现出可用的组织列表,无论你的应用程序中有多少个组织。

根据客户端类型,您可以通过三种方式生成授权令牌。

基于网络的应用程序

当您的应用程序被多个用户使用并在授权过程中需要用户干预时,通常会选择基于Web的应用程序。对于这种客户端类型,您必须使用基于重定向的代码生成。在这个授权流程中,

  • 用户在任何第三方基于网络的应用程序上点击使用Zoho登录按钮。
  • 应用程序将用户重定向到Zoho登录页面,用户输入Zoho凭证。

    "https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.users.ALL&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}"
  • 一个新的弹出窗口,类似于下面的这个,会出现来询问用户选择特定环境的组织,例如生产、沙箱或开发者,应用程序可以访问其数据。这仅适用于具有多个组织的应用程序。

  • 用户选择需要生成授权令牌的组织,然后点击提交。
  • 网络应用程序将用户重定向到Zoho OAuth服务器,并在Accounts URL中提供所需的范围。

    该页面显示了选定的组织和应用程序希望访问的数据(范围)。此外,请求URL具有以下参数:

    • scope:范围限制了应用程序访问受保护资源的级别。请参阅范围以获取更多详细信息。
    • client_id:您在客户端注册期间获得的客户端ID(消费者密钥)。
    • response_type:此参数的值为code
    • access_type:输入access_type为online或offline。如果您想生成刷新令牌,将此值设置为offline。
    • redirect_uri:授权服务器将浏览器重定向回去的URI,带有授权代码。它必须是在API控制台中注册应用程序时提供的相同URI。它应以http://或https://开头。例如:https://www.zylker.com/oauthredirect
  • 根据用户的登录详细信息,系统自动检测用户的域,并使用特定于域的认证URL来获取特定于组织的授权令牌(代码)。
  • 当用户点击接受时:应用程序得到授权。 特定于组织的授权令牌作为参数在redirect_uri中发送。

  • 您需要从上述URL中存储以下详细信息的后端脚本。
    • code={grant_token} - 这用于生成访问和刷新令牌。
    • location={domain} - 这告诉您需要从哪个用户的域进行API调用。
    • accounts-server={accounts_URL} - 这是您需要使用的帐户URL,用于生成访问和刷新令牌。
  • 应用程序将授权令牌交换为访问令牌。
  • 当用户点击拒绝时:浏览器将重定向到带有参数error=access_denied的重定向URI,您的应用程序将被拒绝访问Zoho CRM中的用户数据。

注意

  • 授权令牌仅在两分钟内有效。请参阅令牌有效性页面以获取更多详细信息。
  • 授权URL的范围是用户。您可以根据您的需求更改范围。
可能的错误
  • ERROR_invalid_response_type

    解决方案: "response_type"键的值不是"code"。将值更新为"code"。
    (或)
    您没有在请求中传递必需的键。在请求中传递所有必需的键以生成特定于组织的授权令牌。

  • ERROR_invalid_client

    解决方案: 客户端ID错误或为空。传递正确的客户端ID。您可以从开发者控制台检查您的客户端ID。

  • ERROR_invalid_redirect_uri

    解决方案: 传递的重定向URI值与在开发者控制台注册的值不匹配。传递正确的重定向URI。

  • ERROR_invalid_scope

    解决方案: 范围无效。传递有效的范围。您可以参考这里的范围列表。

自我客户端选项

如果您的应用程序没有域和重定向URL,可以使用此方法生成特定于组织的授权令牌。
当您的应用程序是执行后端任务的独立服务器端应用程序时,也可以使用此选项。

  1. 转到 Zoho开发者控制台,并使用您的Zoho CRM用户名和密码登录。
  2. 从客户类型列表中选择自助客户,然后点击立即创建。
  3. 点击弹出窗口中的确定以启用您账户的自助客户端。
  4. 现在,您的客户端ID和客户端密钥显示在“客户端密钥”选项卡下。

  5. 点击生成代码选项卡,并输入以逗号分隔的所需范围。请参考我们的范围列表,以获取更多详细信息。当您输入一个或多个错误的范围时,系统会抛出一个'输入有效的范围'的错误。
  6. 选择时间长度,即授权令牌的有效期。请注意,过了这个时间,授权令牌就会过期。
  7. 输入描述并点击创建。

  8. 弹出窗口会显示如下所示的门户列表。选择您的门户。此外,弹出窗口会显示每个环境下的环境列表和不同的组织。

  9. 选择您想要为其生成授权令牌的环境中的组织,然后点击创建。
  10. 显示了指定范围的组织特定授权令牌代码。复制授权令牌。

注意

  • 生成特定于组织的授权令牌是一次性过程,只要您在授权令牌有效的时间内生成访问令牌和刷新令牌。