Bearer requests
Send the API key as a bearer token on every public API request.
curl https://login.prospectb2b.com/api/public/v1/me \
-H "Authorization: Bearer pb2b_live_xxxxx_xxxxx"Scope design
Scopes are explicit and should be kept minimal for the integration you are building.
- Use me.read to verify identity and workspace context.
- Use leads.read for incremental sync and leads.write for create or patch flows.
- Use leads.import or leads.export for batch operations and downstream readiness checks.
- Use webhooks.write only for systems that manage webhook endpoints or retries.
- me.read: Read the current API key identity and workspace context.
- leads.read: Read leads, activities and related lead resources.
- leads.write: Create and update leads.
- leads.import: Create lead import jobs and inspect import results.
- leads.export: Create export jobs and download export files.
- lead-fields.read: Read custom lead field definitions.
- messages.read: Read messages associated with leads.
- inbox.read: Read inbox threads and thread messages.
Permission model and read-only implications
Scopes do not override workspace membership. A key can only do what the issuing membership is allowed to do.
- Keys inherit the issuer membership and cannot exceed its permissions.
- Read-only memberships can still authenticate and read data, but write operations are denied.
- Rotating a key creates a fresh secret and revokes the previous record immediately.
- Revoked or expired keys fail authentication even if the prefix still looks valid.
Common authentication failures
These are the operationally relevant cases to monitor in logs or error handlers.
- 401 Unauthorized: missing bearer header, malformed key, revoked key or expired key.
- 403 Forbidden: the key authenticated, but the required scope or membership permission was missing.
- 429 Too Many Requests: the key exceeded the rolling per-minute limit.
- 409 Conflict: a write request reused an Idempotency-Key with a different payload.