Taboola Authentication

generated: '2026-08-13'
method: searched
source: >-
  https://developers.taboola.com/backstage-api/reference/authentication-basics,
  https://developers.taboola.com/backstage-api/reference/client-credentials-flow,
  https://developers.taboola.com/backstage-api/reference/getting-an-access-token,
  https://developers.taboola.com/backstage-api/reference/request-basics,
  https://mcp.realize.com/.well-known/oauth-authorization-server (probed 2026-08-13),
  openapi/*.yml
docs:
  - https://developers.taboola.com/backstage-api/reference/authentication-basics
  - https://developers.taboola.com/backstage-api/reference/client-credentials-flow
provider: Taboola
providerId: taboola
description: |-
  Two OAuth surfaces with very different maturity. The Backstage advertising API uses a
  plain OAuth 2.0 client credentials grant with manually issued credentials and no scopes,
  and the token is presented as a bearer on every call. The Realize MCP server, added
  later, runs OAuth 2.1 with PKCE, discovery metadata and dynamic client registration.
  A previous round derived only the bearer scheme from the OpenAPI; this round upgrades it
  from the provider's own documentation and a live probe.

summary:
  types:
    - oauth2
    - http
  surfaces: 2
  scopes_published: 1
  credential_issuance: manual (Backstage) / dynamic client registration (MCP)

schemes:
  - name: bearerAuth
    type: http
    scheme: bearer
    bearerFormat: opaque
    surface: Backstage API
    in: header
    header: Authorization
    format: 'Authorization: Bearer {access_token}'
    sources:
      - openapi/taboola-accounts-api-openapi.yml
      - openapi/taboola-campaigns-api-openapi.yml
      - openapi/taboola-campaign-items-api-openapi.yml
      - openapi/taboola-conversion-rules-api-openapi.yml
      - openapi/taboola-dictionary-api-openapi.yml
      - openapi/taboola-reports-api-openapi.yml
    note: >-
      The captured specs declare bearerFormat JWT. The docs do not claim JWT and the sample
      token in the client-credentials-flow page is an opaque base64-ish string with a
      "::" delimiter, not a three-segment JWT. Recorded as opaque here; treat the token as
      opaque and do not attempt to parse claims from it.

  - name: backstageClientCredentials
    type: oauth2
    surface: Backstage API
    flow: clientCredentials
    token_endpoint: https://backstage.taboola.com/backstage/oauth/token
    token_request_content_type: application/x-www-form-urlencoded
    parameters: [client_id, client_secret, grant_type=client_credentials]
    scopes: {}
    token_ttl_seconds: 43200
    token_ttl_human: 12 hours
    refresh_token: false
    source: https://developers.taboola.com/backstage-api/reference/client-credentials-flow
    note: >-
      The docs page embeds a one-operation OpenAPI 3.1.0 fragment for this endpoint that
      declares scopes as an empty object for both clientCredentials and the deprecated
      password flow — the provider's own statement that there is no scope vocabulary.
      Permissions ride on the account the client_id identifies. Trailing slash on the
      token URL returns a 403 CSRF HTML page.

  - name: realizeMcpOAuth
    type: oauth2
    surface: Realize MCP
    resource: https://mcp.realize.com/mcp
    issuer: https://mcp.realize.com
    version: OAuth 2.1
    flows: [authorization_code, refresh_token, client_credentials]
    pkce: S256
    authorization_endpoint: https://authentication.taboola.com/authentication/oauth2.1/authorize
    token_endpoint: https://authentication.taboola.com/authentication/oauth2.1/token
    introspection_endpoint: https://authentication.taboola.com/authentication/oauth2.1/introspect
    registration_endpoint: https://mcp.realize.com/register
    token_endpoint_auth_methods: [none, client_secret_basic, client_secret_post]
    scopes:
      all: The single advertised scope. No read-only alternative.
    resource_indicators_supported: true
    discovery:
      authorization_server_metadata: https://mcp.realize.com/.well-known/oauth-authorization-server
      protected_resource_metadata: https://mcp.realize.com/.well-known/oauth-protected-resource
    probed: '2026-08-13'
    http_status: 200
    note: >-
      Full RFC 9728 challenge loop verified live — an unauthenticated tools/list returns
      401 with WWW-Authenticate pointing at the protected-resource metadata document.

credentials:
  backstage:
    issuance: >-
      "Ask your Taboola Account Manager to provide you with a client_id and client_secret."
      There is no self-service developer console for Backstage credentials.
    self_service: false
  mcp:
    issuance: Dynamic client registration at https://mcp.realize.com/register, then Taboola SSO.
    self_service: true

failure_modes:
  detail: ../errors/taboola-problem-types.yml
  modes:
    - status: 401
      cause: Missing Authorization header, or an invalid/expired access token.
    - status: 400
      cause: Bad client credentials at the token endpoint (XML invalid_client fault).
    - status: 403
      cause: Trailing slash on the token endpoint URL (HTML CSRF error from Jetty).

deprecated:
  - flow: password (resource owner credentials)
    deprecated_on: '2024-06-30'
    replacement: client_credentials
    source: https://developers.taboola.com/backstage-api/changelog/password-credentials-deprecation-notice