Debounce Authentication

generated: '2026-08-14'
method: searched
source: openapi/ (securitySchemes) + provider docs
docs: https://developers.debounce.com/api-concepts/authentication
description: >-
  DeBounce authenticates every REST request with an API key passed as the `api`
  query-string parameter. There are no headers to set, no bearer tokens, no OAuth
  and no signing — which is exactly why the docs warn that the key must never be
  placed in client-side code. Two key classes exist with materially different
  posture: a private key with full account access, and a `public_`-prefixed key
  scoped to browser use with CORS domain allow-listing and a hard per-IP daily
  cap. The free Disposable Detector and Logo APIs are unauthenticated entirely. A
  separate OAuth 2.1 authorization server exists on debounce.com, but it belongs
  to the WordPress-hosted MCP endpoint, not to the validation API — see
  scopes/debounce-scopes.yml.

summary:
  types:
  - apiKey
  api_key_in:
  - query
  oauth2_flows: []
  unauthenticated_surfaces:
  - https://disposable.debounce.io
  - https://logo.debounce.com

schemes:
- name: ApiKeyQuery
  type: apiKey
  in: query
  parameter: api
  description: API key for authentication
  sources:
  - openapi/debounce-account-api-openapi.yml
  - openapi/debounce-bulk-api-openapi.yml
  - openapi/debounce-data-api-openapi.yml
  - openapi/debounce-validation-api-openapi.yml

key_classes:
- class: private
  prefix: null
  format: 13-character alphanumeric token
  where: query parameter `api`
  issued_at: https://app.debounce.io/api
  scope: full account access — validation, bulk, enrichment, balance, usage
  limits: 5 concurrent calls; 2 when the enrichment (append) option is enabled
  docs: https://developers.debounce.com/api-concepts/authentication
- class: public
  prefix: public_
  format: '`public_` prefix followed by the key body'
  where: query parameter `api`, from browser JavaScript
  scope: single email validation only, from an allow-listed origin
  cors: the calling domain must be added to the key's approved CORS domain list
  limits: 20 validations per internet IP address per day
  docs: https://developers.debounce.com/api-concepts/rate-limiting

failure_modes:
- http_status: 401
  body: '{"debounce":{"error":"Wrong API","code":"0"},"success":"0"}'
  meaning: API key missing, invalid, or not permitted
  verified: probed
  x-evidence:
    url: https://api.debounce.io/v1/?email=test@example.com
    fetched: '2026-08-14'
    http_status: 401
    note: >-
      Probed with no api parameter. The live response added a "loc" field not
      present in the published Error schema.
- http_status: 402
  meaning: credits exhausted — add credits to continue validating
- http_status: 403
  meaning: request not allowed for this API key or operation
- http_status: 429
  meaning: concurrency limit (private key) or daily per-IP limit (public key) exceeded

guidance:
- >-
  The key travels in the URL query string, so it lands in server access logs,
  browser history, and Referer headers. DeBounce's own docs tell integrators to
  keep the private key server-side; the `public_` key class exists precisely
  because the private key cannot be safely exposed.
- >-
  There is no key rotation, expiry or scoping mechanism documented beyond the
  private/public split, and no OAuth path to the validation API.