主题
账号模型与鉴权
本节介绍 Open API 的两类账号主体及统一的鉴权方式。
账号模型
Open API 涉及两类账号:
- adv_user(主广告主):主账号。凭证为
access_key/api_key,通常配置在调用方环境中(demo 中即.env的ADV_ACCESS_KEY/ADV_API_KEY)。可创建并管理sub_adv_account,也可直接建单(campaign / offer)。 - sub_adv_account(子广告主):从属于某个 adv_user 的子账号,拥有独立的
access_key/api_key。由 adv_user 创建,可使用自身凭证建单(campaign / offer),但不能再创建子账号。
两者关系:
- 一个 adv_user 可创建多个 sub_adv_account。
- sub_adv_account 的凭证由 adv_user 通过
sub_adv_user_name查询获取。 - 建单时可自由选择以 adv_user 或某个 sub_adv_account 的身份进行(详见建单能力)。
统一签名
adv_user 与 sub_adv_account 使用完全一致的签名算法:
timestamp = 当前 Unix 秒级时间戳
token = md5( api_key + md5(timestamp) )请求通过 Header 传递:
| Header | 说明 |
|---|---|
access-key | 鉴权主体(adv_user 或 sub_adv_account)的 access_key |
token | 按上式计算的签名 |
timestamp | 生成 token 时使用的同一时间戳 |
注意:
timestamp与服务端时间偏差需小于 600 秒,请确保调用方本机时间准确。
不同操作使用的鉴权主体:
- 创建 / 查询
sub_adv_account:使用 adv_user 凭证。 - 创建 campaign / offer、上传素材、设置 tracking:使用所选账号(adv_user 或某 sub_adv_account)的凭证。
创建 / 查询子广告主账号
鉴权主体:adv_user
创建 sub_adv_account
- 请求地址:
https://{BASE_URL}/api/open/v3/sub_adv_account - 请求方法:
POST - 关键入参:
sub_adv_user_name、password - 关键返回:
sub_adv_user_name、access_key、api_key、is_unlimited_credit、credit
请求示例:
json
POST /api/open/v3/sub_adv_account
{ "sub_adv_user_name": "demo_sub_01", "password": "******" }查询 sub_adv_account 凭证
- 请求地址:
https://{BASE_URL}/api/open/v3/sub_adv_account - 请求方法:
GET - 关键入参:
sub_adv_user_name - 关键返回:
data.list[],每项含sub_adv_user_name、access_key、api_key
请求示例:
json
GET /api/open/v3/sub_adv_account?sub_adv_user_name=demo_sub_01建单时若选择以 sub_adv_account 身份操作,调用方只需提供
sub_adv_user_name,由 adv_user 凭证查询其access_key/api_key后再签名调用。