Authentication

Lana GraphQL APIs support Keycloak OAuth 2.0 / OpenID Connect access tokens. Each API validates the token's signature, expiry, audience, and configured realm issuer, then uses Lana identity claims for authorization. The partner API additionally supports partner API keys.

Realm and Identity Requirements

Obtain the Keycloak base URL, realm, client ID, and allowed redirect URIs from your Lana administrator. Realm names are instance-specific, typically <instance_name>-internal, <instance_name>-customer, and <instance_name>-partner.

API	Required Lana identity claims
Admin	userId
Customer	partyId
Partner	partnerUserId, partnerId

The claims must identify provisioned Lana entities using UUIDs. The admin and customer APIs also require a Keycloak sub. A token issued successfully by Keycloak does not by itself grant access: the identity must have the necessary Lana permissions.

User Authentication

Use the Authorization Code Flow with PKCE for browser applications, as the admin panel does:

1. Redirect the user to the configured realm's authorization endpoint.
2. Receive an authorization code at an allowed callback URI.
3. Exchange the code using the PKCE verifier for access and refresh tokens.
4. Include the access token in API requests.

Use an OIDC library to handle state, nonce, PKCE, token refresh, and logout. The realm's discovery document is available at:

https://auth.your-instance.com/realms/YOUR_REALM/.well-known/openid-configuration

Service Integrations

Do not assume that a generic client_credentials token can call the Lana APIs. The API still requires the Lana identity claims and application permissions above. The repository's backend Keycloak service accounts manage identities; their existence is not an out-of-the-box service-to-service login for the GraphQL APIs.

Coordinate unattended admin/customer access with your administrator, including identity provisioning, protocol mappers, and least-privilege Lana permissions. Do not reuse the backend's identity-management credentials.

For partner integrations, an authorized partner user can create a revocable API key with the partner API's partnerApiKeyCreate mutation. Send the returned secret unchanged as Authorization: Bearer YOUR_PARTNER_API_KEY to the partner API; it already includes the lana_ prefix. Store it securely; it authenticates a partner-scoped API-key subject, not an admin or customer user.

For local development only, see Authentication (Local Dev) for the passwordless direct-grant example.

Making Authenticated Requests

Include the access token in the Authorization header:

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ me { user { userId email } } }"}' \
  https://admin.your-instance.com/graphql

me returns a wrapper containing user; it does not expose id or email directly.

Token Refresh

The repository's shared Keycloak realm module sets access tokens to 5 minutes, sets the SSO session idle timeout to 24 hours, and enables refresh-token rotation. Deployments can customize these settings; do not assume a fixed refresh-token lifetime or maximum session duration.

Use the token endpoint from the realm's discovery document:

curl -X POST \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "grant_type=refresh_token" \
  --data-urlencode "refresh_token=YOUR_REFRESH_TOKEN" \
  https://auth.your-instance.com/realms/YOUR_REALM/protocol/openid-connect/token

Public SPA clients do not send a client secret. Confidential clients must use the authentication method configured for them. When the response contains a new refresh token, replace the previous one.

Security Best Practices

• Token storage: Keep browser tokens in memory where possible; never embed client secrets in frontend code.
• Logout: Clear local tokens and end the Keycloak session through the OIDC client's logout flow.
• Transport: Use HTTPS outside local development.
• Rotation: Refresh before expiry and retain the newly returned refresh token.
• Permissions: Grant only the Lana roles needed by the integration; authentication and authorization are separate checks.