Authentication

The Solenya API uses OAuth2.1 for authorization. Access tokens are short-lived JWTs (2 hours) issued via token refresh or OIDC login. Refresh tokens (90 days) are rotated on each use and can be revoked individually or in bulk.

For admin/dashboard access, we support OpenID Connect (OIDC) with Google and Microsoft as the identity provider.

Recommendation: Route user queries through your own backend rather than calling the Solenya API directly from the browser. This keeps credentials server-side, lets you log or forward events to your own data pipeline, and makes it easier to roll out changes and run A/B tests. If you do issue tokens directly to frontend clients, scope them to read-only permissions (e.g. index:read:*) to limit exposure.

Required Headers

Every GraphQL API request must include the following headers:

Header	Description
`Authorization`	`Bearer <access_token>`: OAuth2.1 access token (JWT).
`Solenya-Index-UUID`	UUID of the index to query. Required for all `items` queries.
`Solenya-User-UUID`	A valid UUIDv7 identifying the end user. Required for all `items` queries. Generate this client-side and persist it (see Lifecycle Management → Users). The user record is created automatically on first use.

{
  "Authorization": "Bearer <access_token>",
  "Solenya-Index-UUID": "<index_uuid>",
  "Solenya-User-UUID": "<user_uuid>"
}

Scopes

Access is controlled by hierarchical OAuth2.1 scopes in the format {resource}:{action}:{identifier}.

Examples:

Scope	Grants
`index:read:*`	Read all indexes
`index:write:*`	Create and update indexes
`events:write:*`	Submit event tracking data
`account:admin:*`	Full account administration

Scopes are assigned to account users and embedded in access tokens. See Lifecycle Management → Account Users for how to manage them.

Token Exchange

Request an access token using your client credentials via the token endpoint:

Open in Docs ↗

curl -X POST https://api.solenya.ai/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

A successful response returns a short-lived JWT and a refresh token:

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "<refresh_token>"
}

To refresh an expired access token without re-authenticating:

Open in Docs ↗

curl -X POST https://api.solenya.ai/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=<refresh_token>&client_id=YOUR_CLIENT_ID"

For the full OAuth2.1 flow reference, see the live docs at api.solenya.ai/v1/auth/docs.