# Creator authorization flow

The TikTok Shop creator authorization flow with standard endpoints: request the authorization URL, creator authorization with callback confirmation, list authorized creators, and handle expired authorization or missing permissions. The authorized entity is a TikTok account with commerce permission.

- Web document: [Creator authorization flow](/en/openapi/workflows/creator-authorization)
- Markdown: [Markdown](/en/openapi/workflows/creator-authorization.md)
- Operation index: [Operation index](/en/openapi/operations/index.json)

## Flow

```mermaid
flowchart TD
  A["Get authorization URL"] --> B["QR code / browser"]
  B --> C["Grant permissions"]
  C --> D["Confirm authorization"]
  D --> E["Callback redirect (must happen, browser or TikTok app)"]
  E --> F["Authorization successful"]
  E -. "failure: no redirect / no success page" .-> X["Generate a new link and authorize again"]
  F --> G["List authorized creators"]
  G --> H["Account ready for publishing"]
```

## Steps

1. Step 1 · Get the authorization URL: generate the url or QR code on the server for the oauthRegion; never expose the API key.
2. Step 2 · QR code or browser: scan the QR code with a phone, or open the url in a browser.
3. Step 3 · Grant permissions: select the required permissions on the TikTok authorization page; photo posts also need the photo permission.
4. Step 4 · Confirm authorization: confirm with the same TikTok account that has commerce permission and will publish content.
5. Step 5 · Callback redirect (must happen): clicking confirm must automatically redirect to the callback URL (for example https://app.ailingtu.com/oauth/tiktokshop); open it in a browser or inside the TikTok app, not in an embedded WebView.
6. Step 6 · Authorization successful: after the redirect, only “SUCCESS/成功” on the callback page counts as success; one QR code can only be used for one account.
7. Step 7 · List authorized creators: after success pass authSource=TIKTOK_SHOP_CREATOR; add hasPhotoPermission=true for photo posts; store id and creatorId.
8. Step 8 · Manage authorization: expired authorization returns “授权过期，请重新授权”; missing permission requires the creator to grant it.

## Key branches

- **Redirect and confirmation**: confirming must redirect to the callback URL; only “SUCCESS/成功” counts, and no redirect or no success page is a failure.
- **One QR code, one account**: the QR code or authorization URL binds a single account; generate a new one for each creator account.
- **Expired authorization**: account is marked invalid; authorize again and re-query accounts.
- **Missing photo permission**: photo posts need the shoppable photo permission; check with hasPhotoPermission=true.
- **Permission refresh**: use sync to refresh creator permissions when they change; it does not change authorization.
- **Revoke access**: revoke when the creator should no longer publish.

## Endpoint sequence

| Step | Endpoints |
|---|---|
| 1 | [GET /v1/creatorAccount/tiktokShopOauth/authorize](/en/openapi/authorize-creator) |
| 2–6 | No API (QR code, permissions, confirmation, callback redirect and success page) |
| 7 | [GET /v1/creatorAccount/pageList](/en/openapi/creators) |
| 8 | [GET /v1/creatorAccount/tiktokShopOauth/authorize](/en/openapi/authorize-creator) · [POST /v1/creatorAccount/revoke](/en/openapi/revoke-creator) |

## Integration notes

- Authorization URLs are generated per oauthRegion; the market and shop type must match the TikTok account being authorized.
- The authorized entity is a TikTok account; what makes it usable here is its commerce permission.
- Confirming must redirect to the callback URL, and the page must show “SUCCESS/成功” before listing accounts; no redirect or no success page is a failure.
- A QR code or authorization URL binds a single account; never let several creators scan the same code.
- Generate the URL on the server; never expose the API key in browser code, QR codes or logs.
- Photo posts need an extra permission, so confirm it during authorization.
- Store both account id and creatorId after listing accounts.
- Use sync only to refresh creator permissions, not to edit nickname or avatar.
