Bilibili Sanlian Ads Workflow And Authorization Guide

This is the global entry point for Bilibili Sanlian Ads MAPI. Use it first to understand the overall workflow, obtain or load authorization data, resolve the operable advertiser account scope, and then route the concrete task to a domain skill. Endpoint-level field details live in each skill's references/ files.

What This Skill Covers

• OAuth 2.0 authorization and token lifecycle.
• Loading stored credentials from a secure local path.
• Refreshing expired access tokens.
• Guiding the user through authorization when no valid token is available.
• Querying authorized user, subject, advertiser account scope, and account details.
• Routing ad save/query, metadata, reporting, finance, batch operation, and material tasks.

Skill Routing

Authorization Model

All MAPI calls require an access_token. Tokens are generated through OAuth 2.0 authorization. Every new authorization can produce a new access_token and refresh_token; the token's authorization scope determines which Sanlian advertiser accounts can be managed.

A user may authorize multiple times. After each authorization, query the authorized user, authorized subjects, and advertiser accounts, then compare the new token's account scope with stored records. If the scope is the same as a previous authorization, use the new authorization data to replace the older token/refresh token record. If the scope differs, keep the records separate so future tasks can choose the correct account range.

Secure Local Storage

Persist user-provided and API-returned authorization data in a secure local path. After the skill is installed and initialized for the first time, update this skill's description file with the storage path. Future agents using this skill should read that path directly instead of rediscovering it or asking the user again.

Store at least:

• client_id
• client_secret
• access_token
• refresh_token
• callback URL / redirect_uri
• authorized user information
• authorized subjects and advertiser accounts
• selected advertiser account IDs for future workflows
• access_token_expires_at and refresh_token_expires_at
• created time and updated time for each record

Never print, commit, or expose secrets. Use timestamps to judge expiration and to choose the freshest usable authorization record.

Use this JSON shape so independent agents can interoperate:

{
  "version": 1,
  "updated_at": "2026-05-31T00:00:00Z",
  "default_record_id": "sha256:...",
  "records": [
    {
      "record_id": "sha256:...",
      "client_id": "...",
      "client_secret": "...",
      "redirect_uri": "https://example.com/callback",
      "scope": "...",
      "access_token": "...",
      "refresh_token": "...",
      "access_token_expires_at": "2026-05-31T12:00:00Z",
      "refresh_token_expires_at": "2026-06-30T12:00:00Z",
      "authorized_user": {},
      "subjects": [],
      "advertiser_accounts": [],
      "selected_account_ids": [],
      "created_at": "2026-05-31T00:00:00Z",
      "updated_at": "2026-05-31T00:00:00Z"
    }
  ]
}

Generate record_id deterministically from client_id, authorized user ID when available, redirect_uri, sorted subject IDs, and sorted advertiser account IDs. Store all IDs as strings in the credential file to avoid integer precision loss in JavaScript-based agents. When replacing an older same-scope record, preserve created_at and update updated_at.

When updating the credential file, write to a temporary file in the same directory and then rename it over the old file so other agents never read a partially written JSON file.

Token Resolution Flow

Before any real advertiser operation:

1. Load stored authorization records using the credential lookup order above.
2. If a valid access_token exists for the requested user/account scope, use it.
3. If the access_token is expired but a valid refresh_token exists, refresh the token with grant_type=refresh_token, persist the new token values, and continue.
4. If there is no stored token, no usable refresh_token, or refresh fails, guide the user through the OAuth authorization flow below.
5. After a token is available, query authorized user, subjects, advertiser accounts, and account details as needed.
6. Compare the token's account scope with stored records, update or create the local authorization record, then select the target advertiser account_id.
7. Open the domain skill for the requested business task and open the matching reference before composing API requests.

Most business APIs use https://cm.bilibili.com/takumi/api as the root path and require Authorization: Bearer {access_token} plus account_id.

Every MAPI request made through this skill set must include the custom source header below, including OAuth, business API, MAPI upload APIs, reporting, and polling requests. Add it even when a reference cURL example omits it.

X-Call-Source: sanlian-skills

OAuth Authorization Flow

1. Ask the user for client_id and client_secret only if they are not already stored locally.
2. Build the authorization URL:

https://ad.bilibili.com/developer/developer-authorization?client_id={client_id}&state={state}

1. Send the authorization URL to the user and, when the environment allows it, open the URL directly in the user's browser. Guide the user step by step: they should log in, confirm authorization, wait for the browser to redirect, then copy the full URL from the browser address bar.
2. Explain that the redirected page may not look meaningful to them; the important part is the complete callback URL in the address bar, for example https://example.com/callback?code=...&state=....
3. Ask the user to send back the full callback URL after authorization.
4. Extract code from the callback URL. Use the same callback URL without query or fragment as redirect_uri. If token exchange fails with a redirect URI mismatch, try the same callback URL with or without the trailing /; a missing or extra trailing slash may be the cause.
5. Exchange code for access_token and refresh_token with application/x-www-form-urlencoded:

curl --location --request POST 'https://cm.bilibili.com/takumi/api/open_api/oauth2/token' \
  --header 'X-Call-Source: sanlian-skills' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code={code}' \
  --data-urlencode 'client_id={client_id}' \
  --data-urlencode 'client_secret={client_secret}' \
  --data-urlencode 'redirect_uri={redirect_uri}'

1. After authorization is complete, query the authorized user, authorized subjects, and advertiser account list, then persist them locally.
2. Persist the new authorization record with created/updated timestamps and scope information.

Token Refresh

access_token is valid for 24 hours by default. refresh_token is valid for 30 days, and each successful refresh resets the 30-day validity.

Refresh with:

curl --location --request POST 'https://cm.bilibili.com/takumi/api/open_api/oauth2/token' \
  --header 'X-Call-Source: sanlian-skills' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token={refresh_token}' \
  --data-urlencode 'client_id={client_id}' \
  --data-urlencode 'client_secret={client_secret}'

If refresh fails because authorization was revoked, expired, or the refresh token is invalid, restart OAuth authorization.

Authorization Pitfalls

• Do not require the user to understand OAuth 2.0 or run a local callback server. Build the authorization URL for them, send it to them, open it in the browser when possible, and guide them to copy the full callback URL from the browser address bar after authorization.
• If token exchange returns error code 227014 (OAUTH_REDIRECT_URI_MISMATCH), ask for the exact callback URL configured in the developer app and restart authorization with that value.
• When debugging redirect URI mismatch, also compare the trailing slash. https://example.com/callback and https://example.com/callback/ may be treated as different callback URLs.
• Authorization codes are valid for 10 minutes and single-use only.
• When exchanging tokens from a terminal, save the response to a secure local file first instead of relying on stdout; long token strings may be truncated by terminal display.
• For later delivery operations, prefer subjects with subject_type=1 when available. If no subject_type=1 subject exists, other subject types may be used, but handle them cautiously because the account scope may be very large.
• If a subject exposes many advertiser accounts, do not blindly traverse or manage all accounts. Managing more than 1,000 accounts at once can make calls extremely slow and may trigger throttling or account-level penalties because of high request volume.
• Even when the account count is below 1,000, guide the user to provide or approve the subset of advertiser account IDs they actually want to manage. Persist that selected subset and ignore unrelated account IDs for future workflows unless the user explicitly expands scope.

Common Workflows

Create An Ad

1. bilibili-sanlian-ads: load or obtain token, query account scope, and select account.
2. bilibili-sanlian-ads-metadata: query promotion purpose, unit metadata, targeting options, creative locations, and available resources as needed.
3. bilibili-sanlian-ads-materials: upload or prepare image/video materials if needed.
4. bilibili-sanlian-ads-ad-management: create campaign, then unit, then creative.
5. bilibili-sanlian-ads-ad-management: query campaign/unit/creative to verify result.

Query Spend Or Performance

1. bilibili-sanlian-ads: load or obtain token and confirm account scope.
2. bilibili-sanlian-ads-reporting: query custom report metrics.
3. Use bilibili-sanlian-ads-account-finance only when the user asks about cash balance, wallet balance, account budget, fund changes, or cash flow.

Batch Update

1. bilibili-sanlian-ads: load or obtain token and confirm account scope.
2. bilibili-sanlian-ads-ad-management: query current objects first.
3. bilibili-sanlian-ads-batch-operations: submit batch operation.
4. bilibili-sanlian-ads-batch-operations: query task status and details.
5. bilibili-sanlian-ads-ad-management: re-query affected objects if verification is needed.

Guardrails

• Do not guess required or conditional fields. Open the relevant reference file.
• Query account scope before spending, reporting, or write operations.
• Confirm with the user before destructive operations such as delete, tag deletion, or budget changes.
• If a specific domain skill or reference states a maximum QPS, follow that limit strictly to avoid penalties for over-frequency calls.
• Unless a workflow explicitly needs very high concurrency, keep concurrent API traffic at or below 10 QPS.
• When an API reports insufficient QPS, frequency control, rate limiting, or traffic throttling, stop additional calls immediately. Wait 3 seconds and send one retry/probe request. If QPS is still insufficient, wait 5 seconds and send one retry/probe request. Continue with one retry/probe per wait cycle until QPS recovers. Do not resume normal call volume until recovery is confirmed.

Source Document Index