Authentication and scopes
Choose a credential and authorize requests for the correct project.
Credential types
| Client | Credential | How to use it |
|---|---|---|
| A person in a terminal | OAuth access and refresh tokens | Sign in with the CLI; credentials are stored in the operating-system vault. |
| CI, application, script, or AI agent | Expiring service-account token | Supply NEATLOGS_TOKEN through a secret store; use Authorization: Bearer for HTTP. |
| Application sending telemetry | SDK ingest credential | Follow SDK setup. Ingest credentials do not authorize Public API reads. |
| A guest evaluation reviewer | Resource-bound guest token | Only guest-review endpoints accept Authorization: NeatLogsGuest. |
| Existing integration using a legacy Public API key | Legacy project key | Only endpoints explicitly listing the legacy scheme accept it. |
Use the exact dashboard origin for both login and requests: https://app.neatlogs.com
for US, or https://eu.app.neatlogs.com for EU once the public API is deployed
there. Credentials are bound to their issuing deployment and cannot be reused
across regions or environments. The CLI --host value is the origin without an
API path. For EU, the issuer is https://eu.app.neatlogs.com and the resource
audience is https://eu.app.neatlogs.com/api/v1/public; the backend/SDK ingest
URL https://eu.ingest.neatlogs.com is not the login origin.
Project and organization context
For project-scoped requests using OAuth or a service-account token, send:
Authorization: Bearer <access-token>
x-project-id: <project-uuid>OAuth access follows the signed-in user's current membership and project role. A service account must have an active binding to the selected project with an appropriate role. Changing the project header does not grant access to an unbound project.
Discovery and organization operations use the context declared on their endpoint page. For example, the CLI can list projects after human login before a project is saved in the profile. Do not assume every operation requires the same headers.
Some endpoint tables mark x-project-id as optional because legacy project keys carry their own project context. It remains required for OAuth and service-account callers on those project-scoped endpoints.
Scopes and roles
Scopes limit what a credential can request. Your current project role, organization membership, resource ownership, and plan entitlement must also allow the operation. Requesting a scope never grants a role you do not have.
| Scope family | Typical purpose |
|---|---|
context:read | Selected project and actor context |
observability:read, observability:write | Traces, spans, analytics, feedback, and trace metadata |
evaluation:read, evaluation:write | Evaluations, batches, and evaluator workflows |
configuration:read, configuration:write | Detections, prompts, alerts, and project configuration |
project:write | Create or update projects |
sharing:read, sharing:write | Sharing and guest-link workflows |
access:read, access:write | Access and service-account administration |
organization:read, organization:write | Organization data and administration |
billing:read | Billing views |
profile:read, profile:write | Personal profile and preferences |
offline_access | OAuth refresh-token access; this is not an API operation permission. |
The endpoint reference lists each operation's exact OAuth scopes and accepted credentials. Service-account tokens support a subset of scope families; their minting contract lists the available functional scopes. Some personal or administrative operations accept OAuth only.
Token lifecycle
Store human OAuth credentials in the operating-system vault. Store automation tokens in a secret manager, rotate them before expiry, and revoke them when the integration stops needing access. Revoking a service-account token stops subsequent requests without disabling the entire account.
Legacy x-api-key and legacy Bearer schemes apply only where listed. A token's credential type determines its accepted carrier; moving a service-account token into x-api-key does not make it valid.