Oauth2.0授权

Oauth2.0授权

对接 Marketing API的整体流程是什么

如果你要对接巨量引擎Marketing API，整体要经过以下流程：注册为开发者→申请APPID应用→使用授权URL引导广告主完成广告账户授权→使用授权后得到的auth_code换取token→使用token做相关接口调用。

那么在完成开发者注册后，接下来还需要做什么、可能会遇到什么问题、又有什么建议，由于巨量引擎Marketing API的调用和OAuth授权紧密相关，接下来我们将结合授权相关的各个关键点为你做详细介绍。

授权前

为什么要授权（简述 OAuth 2.0 模式）

授权采用的是OAuth2.0授权模式，而OAuth2.0是用于REST/APIs的代理授权框架（delegated authorization framework），它基于令牌Token的授权，在无需暴露用户密码的情况下，使应用能获取对用户数据的有限访问权限。这种模式会为开发者的应用颁发一个有时效性的令牌 token，使得第三方应用能够通过该令牌获取相关的资源。平常我们常见的第三方登录就是使用OAuth 2.0 协议的。同样地，当一个开发者要通过API获取某些广告账户的数据时，也需要得到广告账户的授权。

什么是开发者应用（APPID），怎么申请应用

可以将APPID理解为开发者的应用分组，因为一个开发者可能会需要开发多个应用程序，APPID则是帮助开发者更好地实现独立开发和管理，每个APPID都有独立的secret，并且有独立的授权URL，如上方整体流程说明的开发者应用（APPID）需要获得广告账户的授权才能得到对应广告账户的令牌token，通过token从而进行API的调用，这就是APPID的价值。需要注意的是开放平台的APPID和手机应用的appid没有任何关系，只是一个开发者分组的概念，不要弄混。

那么如何申请应用？当注册成为开发者后，在开放平台的APPID管理模块点击【添加应用】，即可进入新建APPID流程，填写好应用名称、描述等信息即可提交应用申请，我们会在1-2个工作日内完成审核，当审核通过后即可继续后续的流程。下面也将对申请APPID过程中可能遇到的疑问，为你做详细的介绍。

提示：如果还未完成开发者认证将无法新建APPID，请先按提示完成开发者认证。

怎么设置回调地址

回调地址是一个用户自定义的链接地址，用户授权完成后，Marketing API会一并将授权相关的信息和state作为参数拼接至该回调地址，并进行跳转。如何设置和接收回调可详细参考回调地址怎么设置和使用

怎么判断需要哪些权限

请结合自身的开发诉求选择需要的权限，可以提前考虑长期的对接目标，申请时一次性勾选所需的权限，例如如果希望拉取报表那么则勾选上「数据报表」权限点，其他同理。结合你的开发者角色（广告主/代理商/第三方）有如下建议：

如果是第三方角色：请确保只申请需要的权限，应用审核也将更为严格，不合理的权限申请会被拒绝，对于第三方角色暂不开放「广告主信息与资质管理」、「代理商账号管理-创建和修改广告主」、「代理商账号管理-资金和流水管理」权限，第三方如果申请审批会被严格取消，如果需要获取账户信息可以通过广告主公开信息（/advertiser/public_info/）接口查询到账户名、公司名等基础信息。
如果是广告主或代理商角色：因为这类角色操作的是自己公司下的广告账号，可以结合实际需求勾选，也可全选所有权限。

为你提供以下几种应用场景的权限推荐，对应场景建议至少勾选相应权限点，避免有权限缺失：

广告创建管理：账号服务-纵横组织账户管理、账号服务-代理商账户管理-查询代理商下广告主列表（如果需管理代理商账号可选）、广告投放、数据报表、DMP人群管理、工具、青鸟线索通（如果投放的是销售线索类广告可选）；
统计分析：数据报表、广告投放-广告组管理-获取广告组信息、广告投放-广告计划管理-获取广告计划信息、广告投放-广告创意管理-获取创意信息；
素材管理：工具-图片和视频管理、万花筒创意能力。

授权中

授权账号的角色和user的概念及关系

巨量引擎的广告账户体系可以参考下图，***上一层是用户即user的概念，每个user下可以管理多个不同类型的账户，有两类账户类型——纵横组织、代理商。代理商和纵横组织在账户关系上可以理解为广告主账户（adv）的“集合/分组”概念，代理商和管家下会绑定多个不同的adv。

API的授权同样是基于这个账号关系进行。例如下面是广告主点击某APPID授权url后看到的界面，梦一座城（12345678906）就是登录的用户（即user），这个user下管理的所有账户都将显示出来，用户可选择希望授权的广告账户，点击同意就意味着将勾选的账户及对应权限授权给了应用（APPID），授权后开发者可用对应的token通过调用API的方式来操作user下授权的账户。

不同类型账户角色在授权时权限范围也不同，以下针对几个账户概念为你详细介绍：

用户（user）：即user的概念，一个用户可以管理多个广告账户，我们提供了「基于广告账户授权」和「基于用户授权」两种方式，「基于用户授权」即是授权user的含义，按user授权后将获得user下所有广告账户的操作权限，并且user下如果新增了广告账户也将自动赋予权限，详细在下方展开。

管家（管理员）：作为管家的***角色，拥有管家下所有广告主的操作权限。授权管家（管理员）账号后对应的token可调用管家下所有的广告主，并且管家下如果新增了广告主，token也将自动拥有新增广告主的操作权限。

管家（操作者）：作为管家的次级角色，只拥有管家下赋予的部分广告主的操作权限。授权管家（操作者）账号后也只会拥有这部分广告主的权限，但和管家（管理员）一样如果管家（操作者）下新增了广告主，token也将自动拥有新增广告主的操作权限。

代理商：如果用户授权对象为代理商，授权完成后，开发者拥有代理商及代理商直接关联的广告主的操作权限。意味着如果授权了一级代理商那只能操作一级代理商下直接关联的广告主，无法操作二级代理下的广告主，如需操作二级代理的广告主请登录二级代理商账号做授权。

如果你是授权自己公司下的账户，为了减少授权的复杂度，建议和你们公司的广告账户管理同学沟通，用一个企业公共邮箱注册的user，为这个user添加上所有希望通过API管理的广告账户，如下方的user x，然后用这个user x来授权，这样你需要授权一次既可以获得管家A、B、C的权限，也能避免使用个人user授权后人员流动导致user权限失效的问题，例如如果用小红(user y)授权，一旦user y失去管家B的权限，那么使用user y授权得到的token也将无法再调用管家B。

以上是按管家为例，代理商账号同理，也建议使用一个企业公共账号user x来集中绑定所有希望通过API管理的代理商账号，然后用公共user x进行API授权，能有效减少后续的授权及维护成本。

基于广告账户授权和基于用户（user）授权有什么区别，分别适用什么场景

授权时我们有两种授权模式：

基于广告账户授权：授权时将展示出所有可以授权的广告账户，并且可以自由选择希望授权的账户。例如一个user下管理了10个管家账户，可能只希望授权其中一个管家，那么可以在此模式下勾选对应管家账号做授权；
基于用户授权：将授权该用户（user）下的所有广告账户，并且user下如果新增了广告账户，对应user的token也将自动拥有新增账号的权限。例如一个user下管理了10个管家账户，如果基于用户授权，那么授权后的token将拥有user下这10个管家账户的权限，并且如果user下再新增了5个管家，token也将自动拥有这新增的5个管家的权限。

基于广告账户授权：

基于登陆账号授权：

那么这两种模式该怎么选择，核心还是基于自身的授权目的：

例如还是按下方的一个账号场景，user x管理了3个管家，如果你不希望3个管家都授权那就选择基于广告账户授权，只勾选希望授权的管家即可；
如果你希望授权user x下的所有账号，并且考虑未来user x下还会新增新的管家且这个新增管家也希望通过API做调用管理，那么建议使用基于用户授权的方式，授权整个user x。这样user x下的所有账号都完成了授权，包括user x未来新增账号也不需要重新授权，token将自动拥有权限。

再次强调，如果你是广告主或代理商类型的开发者，授权的是自己公司下的账户，建议有意识地管理授权user，使用一个公共user关联上所有希望通过API管理的广告账户，然后用这个公共user做API授权，而不是随便找一个user做授权，这样能避免人员流动带来的一系列账号权限问题。

另外，不管是基于用户授权还是基于广告账户授权，token的管理方式都没有变化，对你来说在调用/oauth2/advertiser/get/接口时会返回所有可操作的管家和代理商账号，作为开发者你不需要知道是基于哪种类型授权的。

如果账号关系发生变更对已授权的token的使用有什么影响

在授权后得到的每一个token都会记录APPID和授权user、授权广告账户、授权权限之间的关系，意味着这个APPID在用对应token调用时也不会超出当时的授权范围。每一次接口调用都会有严格的鉴权，会判断调用的广告账户是否在之前的授权范围内，并且调用的接口是否在当时授权的权限范围内，这步鉴权通过后还会进一步判断user是否仍有对应广告账户的权限，因为user下管理的广告账户是可能变化的。

例如按下图小红的场景，原来小红管理了管家B和管家C两个账号，其中某***adv3移出了管家B，同时移除了小红对管家C的管理权限，小红再访问投放平台的时候已经没有了adv3和管家C（及管家C下广告主）的操作权限，同样的，这时候用小红user y的授权token通过API也无法再调用adv3和管家C，即使之前做过API的授权。所以我们也建议避免使用个人账号做授权管理，尽可能使用一个企业邮箱注册的公共账号如userx，绑定所有希望通过API管理的广告账户，这样能减少账号关系变化带来的接口调用影响。

有几种常见疑问的场景可以自查：

问题一：user下新增了一个新的管家/代理商账户，但是token无法调用原因：例如登录上方的user x做授权，如果你使用的是基于广告账户授权，只勾选了管家A，那么token只会有管家A的权限，如果user x下新增了管家B和管家C想要使用API需要再做授权。解决方法：如果有一个总的user用来管理所有广告账户，可以选择使用基于用户授权的方式，这样授权得到的token将拥有user x下所有的广告账户权限，即使后续新增了广告账户也不需要再次授权。
问题二：原来登录user授权了一个管家，但是突然调用管家下的某个adv提示没有权限了原因：一般是上方小红user y的情况，可以检查是不是出现了user下管理账号的迁移或者变更，例如user y下的管家B不再管理adv3，或者user y不再管理管家C，都会导致API也无法再调用失去权限的广告账户。解决方法：建议使用一个公共账号作为总user，绑定所有要操作的广告账户，然后使用「基于用户授权」模式，这样的话如user x的情况，及时管家A下的adv1迁移到管家B对于user x的token也不会受到影响，能减少个人账户频繁变更的问题。

需要怎么完成授权，有哪些点需要关注

当APPID申请审核通过后，就可以基于授权URL的拼接规则拼接好对应APPID的授权URL，拼接规则的具体信息可以参考：【简版授权流程说明-1授权url】；

如果授权URL没有自定义参数或者修改权限的诉求，也可以使用我们系统推荐的授权URL，可在应用详情页复制得到，如下图所示：

得到授权URL后接下来就需要引导广告主做应用授权，广告主将广告账户授权给APPID后，APPID才能使用对应token进行接口调用。广告主需要访问授权URL并且登录要授权的广告账号，登录后即可见到下图的界面，按需求选择合适的授权模式、勾选需要授权的广告账号点击同意授权即完成了授权。

如果你既是开发者也是广告主需要自己做授权操作，可能遇到以下问题，可以自查：

问题一：在开放平台APPID详情点击授权URL访问后提示没有账号可授权原因：意味着你登录开放平台的user下没有任何广告账户。解决方法：如果你的开放平台的登录user和广告投放平台的登录user不是同一个，建议你授权时候用另一个浏览器或者用无痕模式下去登录广告投放平台的user做授权，避免反复切换账号。

问题二：授权时部分账号已经被选中并且无法取消原因：意味着原来已经授权过该APPID，授权时会自动勾选上当时已经授权的广告账户，为了避免授权时误操作影响历史调用，授权时只可做增量授权。解决方法：如果希望取消原来授权的某些账号，可以在应用管理（https://ad.oceanengine.com/webstore/audit/list.html?rid=m0p7iunzmii）界面操作。

授权后

怎么获取auth_code

有以下方法可以获得auth_code：

方法一：授权回调后在浏览器URL尾部可以复制得到auth_code。这是开发者在调试测试阶段，自己做授权的时候能比较快地获取到auth_code的方法。

方法二：通过回调地址自动接收auth_code等信息，授权后会将APPID、auth_code等授权信息通过回调地址发送给对应开发者，回调地址的开发和接收方案可通过回调地址怎么设置和使用模块详细了解。

怎么做后续token的换取和管理

授权之后如何获取token，并且如何通过token拉取对应的账号列表，可参考下方流程：

***步：授权后会获得auth_code，通过/oauth2/access_token/（获取Access Token）接口可以将auth_code换取对应access_token。

第二步：利用access_token通过/oauth2/advertiser/get/（获取已授权账户）接口可获取token下可操作的账号列表和对应的账号类型——管家（管理员）/管家（操作者）/代理商/广告主（说明：因为历史授权存在直接授权广告主的场景，所以会有广告主类型，但是此次升级后新的授权将不会再有广告主直接授权的情况）。

【示例说明】：如果按下方账号授权后得到的token调用/oauth2/advertiser/get/接口，返回的数据如下图：

第三步：接下来再结合账号类型，利用管家/代理商的广告主查询接口就能知道对应管家/代理商下可操作的广告主有哪些：

如果是代理商账号：通过/agent/advertiser/select/（代理商-广告主列表）接口获取代理商下可操作的广告主列表。
如果是管家（管理员）或管家（操作者）：通过/majordomo/advertiser/select/（管家-广告主列表）接口获取管家下可操作的广告主列表。

什么情况下token会失效，该如何处理

场景一：token超过有效期

对于短期token，access_token有效期为1天，refresh_token有效期30天，超出有效期token将失效。当access_token超时后，可以使用refresh-token（通过/oauth2/refresh_token/接口）刷新，每次刷新都会产生新的access_token和refresh_token，同时重置二者的有效期。

场景二：token被刷新

如果使用refresh_token刷新过，那刷新后老的access_token和refresh_token将继续保留10分钟的有效期，10分钟后会自动过期，请做好token的存储和管理工作，确保每次使用的是***的token。

场景三：广告主取消授权

如果广告主取消授权，access_token和refresh_token会立即失效，开发者将无法通过refresh_token刷新获取access_token和refresh_token。对此，开发者需要让广告主重新授权，使用新的auth_code通过/oauth2/access_token/获取token。

场景四：广告主重新授权

如果广告主重新授权，原access_token、refresh_token会立即失效，开发者需要使用新的auth_code通过/oauth2/access_token/获取token。

怎么解除授权

授权是由广告主账号完成，广告主可以在广告投放平台的服务市场中看到应用管理入口，登录广告账号后可在应用管理页面看到已授权的应用，广告主可以自助进行解除授权：进入应用详情，如果是基于广告账户授权的模式，可以选择单独解除某些广告账户的授权；而基于用户授权不支持单独解除某广告账户授权，如需解除授权可解除整个应用授权。

基于广告账户授权：

基于用户授权：

其他

【敏感物料授权】当调用素材、评论、线索这类物料接口，提示非同主体无法调用时应该怎么处理？

原因：基于数据安全要求，对于素材URL、线索、评论这类相对敏感的物料存在主体的校验，如果开发者主体和查询的广告主主体不一致则无法查询，基于这个要求下代理商、第三方以及公司下存在多主体的广告主都可能遇到此类问题，如果希望做跨主体的物料查询可以通过敏感物料授权解决。

解决方法：可以在授权URL拼接上material_auth=1的参数，这样授权时就会新增敏感物料授权的协议和勾选，引导广告主勾选此项授权后，得到的token就拥有了对应授权账号的敏感物料操作权限，不再受限于主体的一致性。

如何在管家平台/代理商一站式平台进行角色管理和广告账号绑定？

代理商一站式平台：在一站式平台中添加用户（user）并且为用户添加管理账号方式可参考此文档——代理商人员权限配置路径

账户管家平台：在管家平台（也叫客户中心平台）如何添加用户（user）设置管理员/操作者角色，并且为角色添加管理账户，可参考此文档中的权限管理部分——2020-07客户中心操作手册

一般来说一个user下是否可能同时管理管家和代理商的账号？

一般代理商和管家是两类投放角色，所以很少会出现一个user同时既管理代理商账号又管理管家账号，但是也不排除这种可能，逻辑上并无限制，如果一个代理商的管理员使用自己的user再开了个管家账号，就会出现同时管理两类账号的情况。但这并不影响开发者的token管理，只需要按上方介绍的token管理流程，识别好授权的账号类型，调用对应列表接口，即可兼容各种授权场景。

APPID的secret，以及auth_code换取的token分别有什么作用？

APPID审核通过后可以在应用详情页看到对应的secret，这个secret是应用的令牌，会在获取或者刷新token时用到。