Authentication and tenant binding

Bearer authentication format

Send the complete one-time credential in the HTTP Authorization header using the Bearer scheme. Do not add agency or location headers to version 2 private integration requests. The server finds the key record, verifies the secret hash, and derives the authorized agency and location from the stored credential.

Authorization: Bearer <LEAD360_TOKEN>

Use HTTPS and reject redirects to an unexpected host. A credential should be sent only to the official app.lead360.io REST base or MCP URL shown in Developer Settings.

How tenant binding works

Tenant authority is not supplied by the client. Lead360 loads the agency, agency-to-location relationship, active location, scope grants, credential policy, rate state, and service entitlements associated with the stored key. If any required relationship is missing or inactive, authentication fails.

• The operation body cannot override location_id, tenant_id, subaccount_id, agency_id, or account_id.
• Credential and transport fields such as token, secret, password, authorization, headers, endpoint, method, and URL are rejected as operation arguments.
• A discovered operation must have all required scopes and any related service must be enabled.
• Returned records are obtained by tenant-aware adapters using the credential location.

Authentication checks

1. Parse the Bearer credential format and locate the public key identifier.
2. Verify the secret against the stored one-way hash and configured pepper.
3. Require active status and reject expired, revoked, or rotated keys.
4. Validate the owning agency, location relationship, and active sub-account.
5. Enforce any Lead360 operations suspension policy.
6. Consume the per-key rate limit and return rate headers.
7. Load the exact granted scopes and record a durable authentication event.

Authentication failures are intentionally conservative. A client should not distinguish whether an unknown key, incorrect secret, inactive tenant, revoked credential, or ownership mismatch exists beyond the structured public error. This reduces account probing and keeps remediation focused on the approved integration record.

Status response

A successful status response confirms authentication, the agency relationship number, location identifier, public key identifier, service, granted scopes, Bearer authentication mode, credential-based tenant binding, and the MCP path. Treat these identifiers as operational metadata and avoid placing them in public logs or client-side analytics.

{
  "authenticated": true,
  "service": "lead360",
  "scopes": ["contacts.readonly"],
  "authentication": "bearer_private_integration",
  "tenant_binding": "credential_location",
  "mcp_path": "/mcp/lead360/v2"
}