Authentication and security

Nexus uses different credential types for public publisher APIs, member APIs, and OpenRTB.

Product	Credential	Transport
Search API	Scoped publisher API key	Bearer header (preferred), or token query parameter
XML API	Scoped publisher API key	Bearer header (preferred), or token query parameter
Exchange / Demand Stats API	Explicitly scoped member API key and assigned resource	Bearer header (preferred), or token query parameter
MCP	Scoped publisher API key	Authorization: Bearer ...
Advertiser API	Member access JWT or same-origin session	Authorization header or secure cookie
OpenRTB	Partner-specific configuration	Agreed HTTPS bidder endpoint

Query-string compatibility

Search, XML, and Exchange/Demand Stats retain query-string authentication for compatibility. Prefer Authorization: Bearer YOUR_NEXUS_API_KEY. Query strings can appear in browser history, reverse-proxy logs, and monitoring systems. Never paste a production URL containing a real token into chat, email, or screenshots.

Supply exactly one transport. An Authorization header combined with any token parameter returns 400 / API_KEY_AMBIGUOUS, even if both values match. A malformed Authorization header never falls back to a query key. MCP continues to accept Bearer authentication only.

Reporting API key scopes

Scope	Access
publisher:search:read	Search reports and Search link metadata
publisher:xml:read	XML statistics for owned TIDs
rtb:exchange:read	Exchange statistics for IDs granted in members.extra.exchanges.
rtb:demand:read	Demand statistics for DSP IDs granted in members.extra.demands.

The API also enforces member role, tenant ownership, optional source-IP restrictions, expiration, revocation, and rate limits.

RTB requires an explicit matching scope or *; missing, malformed or empty scopes return 403 / SCOPE_REQUIRED. Search/XML accept missing or empty scopes for compatibility. An explicit unrelated scope is rejected by every reporting API.

Machine-readable errors

Errors retain their human-readable message and add a stable code:

{ "status": "error", "message": "Unauthorized: API key has expired", "code": "API_KEY_EXPIRED" }

HTTP	Codes
400	API_KEY_AMBIGUOUS, INVALID_PARAMETERS, INVALID_JSON
401	API_KEY_MISSING, API_KEY_INVALID, API_KEY_DISABLED, API_KEY_EXPIRED, API_KEY_REVOKED, API_KEY_INACTIVE
403	SOURCE_IP_NOT_ALLOWED, SCOPE_REQUIRED, MEMBERS_ONLY, MEMBER_INACTIVE, RESOURCE_NOT_GRANTED
404	NO_DATA
413	REPORT_TOO_LARGE
429	RATE_LIMIT_EXCEEDED
500	INTERNAL_ERROR, CSV_GENERATION_FAILED
503	AUTHENTICATION_UNAVAILABLE, SERVICE_UNAVAILABLE

Match the HTTP status and code, not message text. Authentication or permission failures must not be retried in a loop. Preserve existing HTTP handling: RTB empty JSON and CSV periods still return 404; only their messages differ.

API key activity

For Search, XML, Exchange/Demand Stats, and API-key-authenticated MCP requests, lastUsedAt records the last completed HTTP 2xx response. Key lookups, documentation endpoint discovery, rejected IP or scope checks, redirects, and failed responses do not update it. Usage is written asynchronously for the same active, unexpired, non-revoked key and tenant identity; a write failure does not change the API response. This timestamp does not extend the key's expiration.

Authentication errors

Rejected reporting keys return HTTP 401 with { "status": "error", "message": "..." }:

Message	Meaning
Unauthorized: Invalid API key	No accepted key matches the supplied credential.
Unauthorized: API key is disabled	The matching key has status disabled.
Unauthorized: API key has expired	The matching key has reached its expiration date.
Unauthorized: API key has been revoked	The matching key has been revoked.
Unauthorized: API key is not active	The matching key has a missing or unrecognized status.

Revocation takes precedence over disabled status and expiration; disabled status takes precedence over expiration. XML documentation displays the authentication message instead of the generic ReDoc load error. These messages do not reactivate keys or bypass authentication.

Security audit logs include the rejected key ID and reason, without the credential or HMAC digest. Metrics use only the bounded events api_key_disabled, api_key_expired, api_key_revoked, and api_key_inactive; key IDs are never metric labels.

MCP header

Authorization: Bearer YOUR_NEXUS_API_KEY
Content-Type: application/json

The API key must never be placed in the MCP URL.

Advertiser member token

Authorization: Bearer MEMBER_ACCESS_TOKEN

Search/XML publisher keys are rejected by advertiser endpoints. The backend derives the tenant and advertiser UID from the authenticated member and does not allow the caller to select another member.

Credential handling

• Store secrets in a secret manager or protected environment variable.
• Grant only the required scopes.
• Configure source-IP restrictions where the client has stable egress IPs.
• Rotate and revoke credentials when a machine, user, or integration is retired.
• Redact Authorization, cookies, query tokens, passwords, and API keys from logs.
• Use HTTPS only.