generated: '2026-08-13'
method: searched
source: openapi/tiktok-ads-marketing-api-openapi.yml
docs: https://business-api.tiktok.com/portal/docs?id=1738373164380162
authorization_docs: https://business-api.tiktok.com/portal/docs?id=1738373141733378
summary:
  types: [apiKey, oauth2]
  api_key_in: [header]
  oauth2_flows: [authorizationCode]
  note: >-
    Two different auth systems live behind one brand. The REST Marketing API uses a three-legged
    advertiser authorization that ends in a long-lived opaque token presented as a plain `Access-Token`
    HEADER — not an OAuth bearer token, and not an Authorization header. The MCP server uses real OAuth
    2.1: authorization code + PKCE, dynamic client registration, refresh tokens, and RFC 9728 / RFC 8414
    discovery metadata that TikTok actually serves. An agent that can talk to the MCP server therefore has
    a far more standard credential story than one calling the REST API directly.
schemes:
  - name: AccessToken
    type: apiKey
    in: header
    parameter: Access-Token
    surface: REST Marketing API
    description: >-
      Long-term access token for the Marketing API. Issued by POST /oauth2/access_token/ (Content-Type
      application/json) or POST /oauth/token/ (application/x-www-form-urlencoded), exchanging app_id +
      secret + auth_code. Sent on every subsequent request in the Access-Token request header.
    sources: [openapi/tiktok-ads-marketing-api-openapi.yml]
    spec_note: >-
      In the first-party OpenAPI fragments the token is declared as a QUERY parameter named Access-Token on
      every operation. The docs and every published curl example send it as a HEADER
      (--header 'Access-Token: ...'), and the 40104 error body returned by a live unauthenticated call says
      "you should set it in http header with key Access-Token". The header form is authoritative; the spec
      is wrong here, and this artifact records the header form.
  - name: MCPOAuth
    type: oauth2
    surface: TikTok for Business MCP Server
    flows:
      - flow: authorizationCode
        authorizationUrl: https://business-api.tiktok.com/portal/mcp-tt4b-authorize
        tokenUrl: https://business-api.tiktok.com/open_mcp/tt-ads-mcp-flat/oauth/token
        scopes:
          mcp:tt4b: Act on TikTok Ads resources on behalf of the authorizing TikTok for Business user
    pkce: [S256]
    dynamic_client_registration: https://business-api.tiktok.com/open_mcp/tt-ads-mcp-flat/oauth/register
    revocation_endpoint: https://business-api.tiktok.com/open_mcp/tt-ads-mcp-flat/oauth/revoke
    jwks_uri: https://business-api.tiktok.com/open_mcp/tt-ads-mcp-flat/oauth/jwks
    grant_types: [authorization_code, refresh_token]
    token_endpoint_auth_methods: [none]
    sources:
      - well-known/tiktok-ads-oauth-authorization-server-mcp-flat.json
      - well-known/tiktok-ads-oauth-protected-resource-mcp-flat.json
flow:
  rest:
    - Register as a developer and create a developer app on the TikTok API for Business portal.
    - Select the permission scope for the app (see scopes/tiktok-ads-scopes.yml).
    - Send the app's Advertiser authorization URL to the advertiser; up to 10 redirect URLs may be configured, localhost included.
    - The advertiser approves the permission list, agrees to the Platform Service Agreement, and confirms an emailed verification code.
    - TikTok redirects to your redirect_uri with auth_code appended; auth_code is valid for 1 hour and single-use.
    - POST app_id + secret + auth_code to /oauth2/access_token/ to receive access_token, advertiser_ids[] and the granted scope[].
    - Send Access-Token on every subsequent request.
  mcp:
    - Point an MCP client at one of the two server URLs; no developer app or API key is required.
    - The client is challenged with 401 + WWW-Authenticate carrying the RFC 9728 resource metadata URL.
    - Standard OAuth authorization-code + PKCE flow against the discovered authorization server, with dynamic client registration.
    - The user signs in to TikTok Ads Manager and authorizes; the grant lasts 30 days and must then be renewed.
token:
  type: opaque
  expiry: >-
    The Marketing API long-term access token does not expire on a timer. It becomes invalid when the
    advertiser cancels the authorization, or when it is explicitly revoked via /oauth2/revoke_token/.
  revocation_endpoint: /oauth2/revoke_token/
  refresh: not applicable for the long-term Marketing API token; the MCP OAuth token supports refresh_token
  introspection_endpoint: /oauth2/advertiser/get/
  introspection_note: returns the full list of advertiser accounts an access token can reach
  scope_note: >-
    The token carries only the permissions the ADVERTISER granted, which may be narrower than the
    permissions the developer app requested.
verification:
  advertiser_reauth_window_hours: 48
  note: >-
    An ad account that has already authorized a given developer app does not have to re-verify by email for
    48 hours. Authorizing a DIFFERENT developer app always requires a fresh verification.
sandbox:
  base_url: https://sandbox-ads.tiktok.com/open_api
  note: sandbox access tokens are generated per developer app; see sandbox/tiktok-ads-sandbox.yml