Connect a backend

There are two ways to authenticate, and choosing correctly matters more than anything else in this page. Pick based on who owns the user’s identity for your system.

	sollar-exchange	external-oauth
Use when	Your backend can trust Sollar as the identity provider	Your system has its own IdP and will not delegate
The user sees	Nothing — it is silent	A sign-in screen from your IdP, in the system browser
You receive	A short-lived, audience-restricted token	A token from your own IdP
Effort	One manifest field	An OAuth client, plus PKCE

Default to sollar-exchange. Reach for external-oauth only when your system genuinely owns the identity.

Delegating identity to Sollar

manifest.json

"auth": {
  "type": "sollar-exchange",
  "audience": "acme-erp-api",
  "scopes": ["orders.read", "orders.approve"]
}

const { token } = await sollar.auth.getToken()
await fetch('https://erp.acme.example/approvals', {
  headers: { Authorization: `Bearer ${token}` },
})

Behind that, the native Sollar client — which is the confidential OAuth client, not your mini app — performs an RFC 8693 token exchange against Keycloak:

POST /realms/{tenant}/protocol/openid-connect/token
grant_type    = urn:ietf:params:oauth:grant-type:token-exchange
subject_token = <the user's Sollar token>
audience      = acme-erp-api
scope         = orders.read orders.approve

Your backend then validates the result the way it would validate any JWT: signature against the tenant’s JWKS, aud equal to your audience, exp in the future, iss the expected realm.

your backend

const claims = await verifyJwt(bearer, {
  jwks: `https://auth.sollar.com/realms/${tenantId}/protocol/openid-connect/certs`,
  audience: 'acme-erp-api',
})
const userId = claims.sub          // the app_user_id — stable for YOUR mini app only

A token minted for your mini app is useless in another. The audience restriction is what guarantees it: if your token leaks, the next mini app’s backend rejects it on aud.

Mapping Sollar users to your users

claims.sub is the app_user_id — derived per (user, mini app), so two mini apps serving the same person receive different, non-correlatable identifiers. This is intentional: it is what stops a mini app store from becoming a tracking network.

For your first sign-in you therefore need a linking step. Ask for sollar.identity.basic, use the email or employee ID your tenant has configured, and store the mapping on your side. Afterwards, app_user_id is your stable key.

Signing in against your own IdP

manifest.json

"auth": {
  "type": "external-oauth",
  "issuer": "https://login.acme.example",
  "client_id": "acme-erp-miniapp",
  "scopes": ["openid", "profile", "orders"]
}

await sollar.auth.signIn()             // opens the system browser
const { token } = await sollar.auth.getToken()

signIn() opens ASWebAuthenticationSession on iOS or Custom Tabs on Android. The user sees a real browser, with a real address bar and a real lock icon. The host exchanges the code with PKCE and stores the result in the OS keychain; your mini app never sees the refresh token.

This never happens inside the mini app’s WebView

RFC 8252 §8.12 forbids embedded user-agents in OAuth flows for native apps, and the reason is concrete: inside a WebView the user cannot verify the URL or the certificate, and the host application is technically capable of reading the typed password.

A third-party mini app asking for corporate credentials inside a WebView controlled by another third party is precisely the attack the RFC describes. Sollar will not offer an API to do it, and no customer request will change that — including “to make it feel more integrated”.

Sending a request from your backend to Sollar

When your backend calls Sollar — to post a card, say — sign the request:

base      = "v0:" + timestamp + ":" + raw_body
signature = "v0=" + hex(HMAC_SHA256(signing_secret, base))

X-Sollar-Signature: v0=…
X-Sollar-Request-Timestamp: 1756704000

Compare in constant time, and reject a timestamp outside a short window to block replay.

Rules that do not bend

No long-lived secret reaches the mini app. No client_secret, no API key, no refresh token, no signing key. If your design needs one in the browser, the design is wrong. WeChat documents the same rule about its own session_key, and for the same reason.

Client-side identity is a suggestion until your server validates it. Always.

Call getToken() per use. Do not cache it, do not persist it, do not pass it on.

Network hosts live in the manifest. erp.acme.example must be in network.connect or the request is blocked by native code before it leaves the device — regardless of what your CSP says.

When an agent calls on the user’s behalf

If a Sollar AI agent invokes one of your actions, the token carries two identities: the user it acts for, and the agent acting. RFC 8693 actor_token produces an act claim:

{
  "sub": "app_user_9f3c…",
  "act": { "sub": "agent:workforce/approvals-assistant" }
}

Your backend can distinguish “Ana approved this” from “Ana’s agent approved this” — which matters for audit, for spending limits, and for incident investigation. Read the act claim and record it.