Dataforseo Authentication

generated: '2026-08-13'
method: searched
source: openapi/*.yml (12 documents)
docs: https://docs.dataforseo.com/v3/auth/
probed:
  - {url: 'https://api.dataforseo.com/v3/appendix/user_data (unauthenticated POST)', http_status: 401, fetched: '2026-08-13'}
  - {url: https://data.dataforseo.com/.well-known/oauth-authorization-server, http_status: 200, fetched: '2026-08-13'}
  - {url: https://mcp.dataforseo.com/.well-known/oauth-protected-resource, http_status: 200, fetched: '2026-08-13'}

summary:
  types: [http, oauth2]
  http_schemes: [basic]
  oauth2_flows: [authorizationCode]
  api_key_in: []
  note: >-
    Two distinct surfaces with two distinct auth models. The v3 REST API is HTTP
    Basic ONLY — all 554 operations across all 12 specs declare a single
    `basicAuth` scheme and nothing else. OAuth 2.0 exists only on the hosted MCP
    server, which is a separate host with its own authorization server.

schemes:

  - name: basicAuth
    type: http
    scheme: basic
    surface: REST API (https://api.dataforseo.com, https://sandbox.dataforseo.com)
    header: 'Authorization: Basic base64(login:password)'
    credentials_source: https://app.dataforseo.com/api-access
    registration: https://app.dataforseo.com/register
    realm: DataForSEO REST API
    notes:
      - >-
        The API password is generated by DataForSEO and is different from the
        account password.
      - Credentials cannot be passed as URL parameters.
      - >-
        No separate authentication call exists — there is no token endpoint on
        the REST API; credentials accompany every request.
      - >-
        The same credentials work against the free sandbox host; there is no
        test-vs-live key separation.
      - >-
        Account verification (email and/or phone) is required before API access
        (status_code 40104).
      - >-
        IP whitelisting is available in the account dashboard and is enforced
        with status_code 40207.
    sources:
      - openapi/dataforseo-aioptimization-api-openapi.yml
      - openapi/dataforseo-appdata-api-openapi.yml
      - openapi/dataforseo-appendix-api-openapi.yml
      - openapi/dataforseo-backlinks-api-openapi.yml
      - openapi/dataforseo-businessdata-api-openapi.yml
      - openapi/dataforseo-contentanalysis-api-openapi.yml
      - openapi/dataforseo-dataforseolabs-api-openapi.yml
      - openapi/dataforseo-domainanalytics-api-openapi.yml
      - openapi/dataforseo-keywordsdata-api-openapi.yml
      - openapi/dataforseo-merchant-api-openapi.yml
      - openapi/dataforseo-onpage-api-openapi.yml
      - openapi/dataforseo-serp-api-openapi.yml

  - name: oauth2
    type: oauth2
    surface: MCP server (https://mcp.dataforseo.com)
    issuer: https://data.dataforseo.com
    flows:
      - flow: authorizationCode
        authorizationUrl: https://data.dataforseo.com/oauth/authorize
        tokenUrl: https://data.dataforseo.com/oauth/token
        refreshable: true
        scopes: {api: Access to the DataForSEO API, profile: Access to the account profile}
    pkce: [S256]
    token_endpoint_auth_methods: [none]
    dynamic_client_registration: https://data.dataforseo.com/oauth/clients/register
    revocation: https://data.dataforseo.com/oauth/tokens/revoke
    bearer_methods_supported: [header]
    discovery:
      authorization_server_metadata: https://data.dataforseo.com/.well-known/oauth-authorization-server
      protected_resource_metadata: https://mcp.dataforseo.com/.well-known/oauth-protected-resource
    sources:
      - well-known/dataforseo-oauth-authorization-server.json
      - well-known/dataforseo-oauth-protected-resource.json
    note: >-
      Not declared in any OpenAPI document — discovered by probing the MCP host's
      RFC 9728 metadata and the authorization server's RFC 8414 metadata.

  - name: env-credentials
    type: http
    scheme: basic
    surface: MCP stdio transport and CLI
    env: [DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD]
    note: >-
      OAuth is not available on stdio or the CLI; those modes require the same
      Basic credentials supplied through environment variables. On the HTTP
      transport, env credentials are the fallback used when no Authorization
      header is present.

auth_errors:
  - {code: 40100, meaning: not authorized / credentials do not match}
  - {code: 40104, meaning: account not verified (email/phone verification required)}
  - {code: 40201, meaning: unusual activity — account access restricted}
  - {code: 40207, meaning: IP not whitelisted}

related:
  - {type: OAuthScopes, url: scopes/dataforseo-scopes.yml}
  - {type: Conventions, url: conventions/dataforseo-conventions.yml}
  - {type: MCPServer, url: mcp/dataforseo-mcp.yml}