Authentication and authorization models vary across Site Search API families. This article summarizes the credential patterns used across runtime, discovery, analytics, and administration APIs so you can choose the correct header or token format for each endpoint.
Authentication Models by API Family
| API Family | Typical Header or Credential Pattern | Notes |
|---|---|---|
| Search / Ingest runtime APIs | Authorization: Token <token> (or Basic auth where app-configured)
|
Write operations require write-capable credentials. |
| Discovery endpoints (Related/Popular) | Authorization: <DISCOVERY_API_KEY> (raw key)
|
Do not add a Token prefix for these endpoints.
|
| Geocoding |
Authorization: Token <DISCOVERY_API_KEY>
|
Requires the app_id query parameter on endpoint calls.
|
| Smart Answers |
Authorization: Token <read-only-token>
|
Missing headers can return 401. Some failures can appear as payload-level errors in a 200 response.
|
| Analytics Tracking | Payload key in event (properties.key)
|
Does not use token-header authentication for event acceptance. |
| Analytics Reporting |
Authorization: Token <reporting-key>
|
Missing or invalid format can produce 401 or 403.
|
| Administration APIs |
Authorization: Token <token>
|
The token is obtained through the administration authentication endpoint. |
Token Lifecycle (Administration API)
- Obtain token:
POST /api/rest/v2/obtain-auth-token/ - Verify token:
GET /api/rest/v2/verify-auth-token/
Credential Scope Guidance
- Use read-only credentials for search and query-only paths.
- Use read-write credentials only for write or update operations.
- Keep administration credentials separate from runtime app credentials.