Skip to main content

Authentication

Numeraire SwissKnife supports multiple authentication methods:

JWT (auth_provider = "jwt")​

JWT authentication gives the initial admin account full access via the sign-in endpoint. It only requires jwt.secret to be set in the configuration file (and optionally jwt.token_expiry).

The admin password is not set in the configuration file. On first launch you set it through the sign-up endpoint, which stores it hashed in the database. The local auth identity subject is fixed as admin.

Local JWT is the installation owner login. Password changes use POST /v1/auth/change-password; per-account local credential management is not part of 0.3.0. Use OAuth2/OIDC for external identity providers.

See the configuration values for JWT here.

OAuth2 (auth_provider = "oauth2")​

OAuth2 authentication allows users to sign in with their OAuth2 provider. The domain and audience need to be set in the configuration file.

oauth2.domain is the OpenID provider issuer base URL. Numeraire SwissKnife resolves the JWKS URI and the canonical issuer from this base via OpenID Connect (OIDC) discovery (the scheme defaults to https when omitted), so it works with any OIDC-compliant provider, not just Auth0. It will then automatically fetch the JWK Set in intervals (jwks_refresh_interval) from the provider and validate the JWT, enabling key rotation.

On the first authenticated request, the provider's sub is idempotently mapped to an account and that account's native-BTC wallet for the configured network is made available. Concurrent first requests resolve to the same account and wallet.

See the configuration values for OAuth2 here.

Tested with Auth0.

API keys​

In addition to JWT and OAuth2, requests can be authenticated with an API key. API keys are created per account and can always use that account's ownership-scoped /v1/me routes. Their permission array grants additional administrative API access.

Not finding your preferred auth method?​

If you want to use a different authentication method, please open a feature request on our GitHub repository.