Kua and Kola

Choose the right journey

Personal sign-in does not authorise company data access. A company connection does not consent on behalf of every individual. Neither flow grants a general payroll-payment API.

This is a registered Kola integration. The current contract does not provide a general developer self-service OAuth app-registration program. Company SDK API keys are not substitutes for the registered client or per-link signing secret. Ask the integration owner to configure the environment and allowlisted callbacks before implementing a new client.

Personal sign-in with PKCE

1. Start Continue with Kua in Kola. The registered client is kola. It creates a fresh state, nonce and PKCE verifier; derives the S256 challenge; and uses the environment’s discovery document at /.well-known/openid-configuration to find its configured authorisation endpoint.
2. The request uses response_type=code, registered redirect_uri, scope containing openid (optionally email profile), state, nonce, code_challenge and code_challenge_method=S256. The person signs in to Kua, verifies their account if required, reviews consent and approves or cancels.
3. Kola validates the callback state against the initiating browser session. A returned code is single-use and expires after two minutes. Exchange it once with the original redirect URI and verifier. Never send a company API key or client secret as a replacement.
4. Validate the ID token’s signature against the discovered JWKS, expected issuer, audience kola, expiry and original nonce. Use the access token for userinfo. The current tokens expire after ten minutes; there is no refresh-token grant. Kola’s application-session lifetime is a separate policy.
5. Establish the Kola session only after validation. If organisation_id was requested, Kua also requires active membership in the linked organisation and applicable link consent; personal-only sign-in does not require an employer connection.

The following form is for the registered Kola server, after a real approved callback. All variables must come from that transaction and its configured environment:

curl --fail-with-body "https://api.kuahr.com/v1/oauth/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=kola' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=$REGISTERED_REDIRECT_URI" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"

Success returns access_token, token_type, expires_in, id_token and scope with no-store cache headers. Keep token responses out of logs and shared caches.

curl --fail-with-body "https://api.kuahr.com/v1/oauth/userinfo" \
  -H "Authorization: Bearer $OIDC_ACCESS_TOKEN"

The bearer token is the access token, not the ID token and not a kua_live_… API key. Userinfo is subject to the granted scopes and current eligible link/membership for organisation-scoped tokens.

Company connection and consent

1. An authorised Kola organisation administrator starts the company connection in Kola. Its configured server creates a signed, expiring connection request with organisation identity, requested scopes and an allowlisted return address.
2. The company administrator signs in to Kua, selects an eligible company and reviews the exact organisation and grants. Settings permission and fresh identity confirmation are required; personal OIDC consent does not replace them.
3. The administrator approves only the requested permissions they intend to grant, or cancels. Approval produces PendingExchange, not a complete synchronisation. Kola validates state and exchanges the one-time code through the configured server-to-server integration.
4. Successful exchange yields the link ID and one-time per-link signing secret to the configured server; store it securely. The link becomes Active. That secret is neither a company API key nor an OIDC token.
5. Verify the link and scopes in both products, then verify activation/event delivery and the destination record. An Active label, queued outbox event or HTTP acceptance alone does not prove directory or culture data arrived.

Common company grants are organisation.identity, directory.read and culture.values.read. Optional write capabilities, such as recognition.write, require explicit consent and the supported destination flow; never infer permission from a listed scope alone. Company connection and signed snapshot routes are integration-management routes, outside the public company SDK contract.

Synchronisation and revocation

With the relevant grant, Kola makes signed per-link requests for directory and culture snapshots. A directory with no eligible employees or a company with no culture values can validly return an empty result. Check the selected company, granted scopes and source records before treating empty as a transport failure. Directory consent does not include general salary, wallet or payroll access.

On disconnect, verify Revoked on both sides and that the old link cannot fetch data or publish a new activation. Queued work must be checked against current link authority; a stale event from the old link cannot silently reactivate it. Reconnection is a new consent/exchange journey, not reuse of the old signing secret. Revoking the company link does not imply deleting the person’s separate Kola account or historical records.

Failures and interrupted journeys

Done when: the intended personal session or company connection is verified at its destination, cancellation is handled, and disconnect/revocation behaves as expected. Review the public reference for the two OIDC operations and the go-live checklist for environment and operational ownership.