Misar IO Docs

Authentication

The two auth modes of the Universal Wallet: SSO bearer for self-access and x-wallet-service-key for server-to-server billing.

The Universal Wallet supports two authentication modes. Which one an endpoint accepts depends on whether the call reads a user's own data or charges/mutates on their behalf.

SSO bearer (own user)

A signed-in user can read their own wallet using their Misar SSO access token:

Authorization: Bearer <sso_access_token>

With a bearer token, the wallet derives user_id from the token — you do not pass user_id. This mode is accepted by the read endpoints:

  • GET /io/wallet/balance
  • GET /io/wallet/transactions

A bearer token can only ever access the balance and history of the user it belongs to.

Service key (server-to-server)

Trusted backend services authenticate with a shared service key:

x-wallet-service-key: <WALLET_SERVICE_KEY>

With the service key, the caller acts on behalf of any user and must specify which one:

  • Read endpoints take ?user_id=<id> in the query string.
  • Write endpoints take user_id in the JSON body.

Never expose the service key

WALLET_SERVICE_KEY is a server-only secret. It bypasses per-user authorization. Never ship it to a browser, mobile app, or any client bundle. Store it in your platform's secret manager (macOS Keychain locally, Coolify env in production) and read it at runtime.

Which mode each endpoint accepts

Prop

Type

Environment variables

VariableUsed byPurpose
WALLET_API_URLCalling servicesBase URL override. Default https://api.misar.io/io/wallet.
WALLET_SERVICE_KEYCalling servicesServer-to-server credential sent as x-wallet-service-key.

On this page

SSO bearer (own user)Service key (server-to-server)Which mode each endpoint acceptsEnvironment variables