Apps

UMA Auth

UMA Auth is not a wallet and not a social client. It is a protocol flow: a client app uses OAuth to ask an UMA-enabled wallet for a scoped Nostr Wallet Connect capability, then uses that capability to request payments, balances, budgets and related wallet actions.

Apps The product layer Clients, signers, publishing tools, wallets and useful experiments.

Directory Signers Login

Apps25 min readUniversal Money Address auth extension, OAuth 2.0 wallet connection, Nostr Wallet Connect, app identity keys, VASP server flows and cross-currency budgets

UMA Auth

The quick readUMA Auth is an extension of Universal Money Address, the Lightning-address-inspired protocol from the UMA project. The docs describe UMA Auth as a combination of UMA, OAuth 2.0 and Nostr Wallet Connect. A client app redirects the user to an UMA provider, the provider authenticates the user and asks for permission, the app receives an authorization code, and the app exchanges that code for an NWC connection string plus tokens. That connection can then be used for supported NWC-style commands such as balance, invoice, payment, budget and transaction requests, with UMA-specific cross-currency behavior around addresses and budget accounting. The important boundary is that UMA Auth does not make every NWC wallet an UMA wallet and does not make every app safe. The app has its own Nostr identity keypair and kind 13195 registration event, the redirect URI and NIP-05 proof matter, the VASP side may run the UMA NWC Docker image, and the NWC connection URI, access token and refresh token are sensitive wallet capabilities. Before using it, verify the provider, registration event, commands, budget, token storage, relay, revocation path, currency conversion rules and whether the wallet or VASP is regulated or custodial.

What UMA Auth really is

UMA Auth is a protocol extension around Universal Money Address, OAuth 2.0 and Nostr Wallet Connect. The official introduction says UMA Auth lets users connect UMA-enabled wallets to third-party applications, and the protocol overview describes a client app starting an OAuth flow, receiving an authorization code, exchanging it for an NWC connection string and refresh token, then using the NWC connection to send and receive payments.

That makes UMA Auth different from a wallet product. You do not install UMA Auth as a normal app and then keep funds inside it. A wallet or VASP implements the UMA side, a client app integrates the connection flow, and Nostr relays carry encrypted wallet requests once the connection exists. UMA Auth is the handshake and permission system that joins those pieces.

The word UMA can also collide with older identity language such as User-Managed Access. This page is not about that. Here UMA means Universal Money Address, the open-source money-address protocol associated with uma.me and the `uma-universal-money-address` GitHub organization. Its Auth extension is specifically about payment apps, Lightning, NWC, OAuth UX and cross-currency wallet permissions.

Why it belongs with protocols

UMA Auth belongs in Protocols because the reader's main questions are not about a single user interface. They are about which messages move, who signs or redirects, where the NWC capability comes from, which commands the app may call, how the budget is enforced and how the connection can be revoked. Those are protocol and integration questions.

The visible experience can be as simple as a connect button. The client quick start shows an `UmaConnectButton` for React and a web component option for plain HTML. But that button is only the front door. Behind it are an app identity public key, a Nostr relay URL, a redirect URI, required commands, optional commands and requested spending limits by amount, currency and period.

That is the useful mental model: OAuth gives the user a familiar permission screen, UMA gives the money-address and cross-currency context, and NWC gives the app a relay-based wallet-control channel. If one of those pieces is weak or misunderstood, the nice button does not make the setup safe.

The base UMA layer

Universal Money Address is a payment-address protocol built on Lightning Address and LNURL ideas. The UMA docs describe addresses that look like `$alice@example.com`, with the leading dollar sign differentiating an UMA address from an email address and from a plain Lightning Address. The address domain starts the LNURL-style lookup, and the protocol adds UMA-specific requirements around counterparties, signing and payment context.

This matters because UMA Auth inherits more than a brand name. It is not just an OAuth wrapper around any arbitrary NWC wallet. It is meant for UMA-enabled wallets and VASPs, where a user can have a money address, receive or send in a preferred currency and let another app ask for payment actions without building the whole payment stack itself.

If you are evaluating a wallet, first ask whether it is actually UMA-enabled. A normal Lightning wallet may support NWC perfectly and still not support UMA Auth. A provider may support UMA payments and still expose only part of the Auth surface. The article-worthy detail is the overlap, not the labels.

The OAuth shape of the flow

The official UMA Auth overview deliberately uses the OAuth 2.0 shape that many users and developers already know. A client app redirects the user to the provider authorization endpoint. The provider authenticates the user, shows permissions, and redirects back to the client app with an authorization code. The client then exchanges that code for wallet connection material.

That familiar UX is valuable because wallet connections are hard to explain. Users have learned to approve scopes in web services. UMA Auth borrows that pattern, but the result is not just an account-login token. The app ultimately receives an NWC connection string and token state that can be used to make wallet requests within the permissions and budget approved by the user.

This is the first place to be careful. OAuth does not magically make wallet access harmless. Redirect URIs must match the registered app. The user must recognize the provider and app identity. The client must protect the returned code, tokens and NWC URI. A phishing page that tricks a user into approving the wrong app can be much more serious when the approved scope includes payment commands.

What comes out of OAuth

After authentication, the client app has access to an NWC connection, the granted permissions, spending limits and related authentication data. The client quick start tells developers to check granted permissions before deciding which NWC methods to invoke. That is the right posture. A good app does not assume it can pay invoices merely because the connect button succeeded.

The SDK examples show balance fetching, direct use of an `NwcRequester`, and support for methods such as `getInfo`, `getBalance`, `getBudget`, `payInvoice`, `payKeysend`, `makeInvoice`, `lookupInvoice`, `listTransactions`, `lookupUser`, `fetchQuote`, `executeQuote` and `payToAddress`. Actual support still depends on the user's wallet and provider implementation.

The client-side result should be treated as a wallet capability. The docs explicitly warn that the NWC connection string, access token and refresh token are highly sensitive because they provide access to a user's wallet and spending limit. That warning should shape every app design decision: storage, logging, analytics, backend handoff, token refresh and account recovery.

App identity is a Nostr object

UMA Auth does something subtle and important with Nostr before the wallet requests begin. A client application has a single Nostr identity keypair for the app itself. The app registration guide says this identity keypair is the same for all users of the application. The app then publishes a Nostr app registration event, kind 13195, signed by that key.

The registration event carries user-facing and security-sensitive metadata: app name, description, image, allowed OAuth redirect URIs and a NIP-05 address. The docs recommend publishing to public, reputable relays so the app registration can be found. This is how the UMA provider can connect an OAuth request to a recognizable app identity instead of a random redirect URL.

For readers, the practical check is simple: the app identity should line up. The public key, relay, redirect URI, logo, NIP-05 domain and app name should describe the app you think you are connecting. If a payment app cannot explain its identity event or uses a strange redirect domain, treat that as a serious warning, not as cosmetic metadata.

NIP-05 is part of the trust story

The registration guide asks apps to verify identity with NIP-05 by serving `/.well-known/nostr.json` on the app domain. The special `_` name can map to the app identity public key, and the domain must match the NIP-05 address in the registration event. That creates a link between the signed Nostr event and a domain the app controls.

This does not prove that the app is safe, solvent or bug-free. It proves a narrower but useful thing: the same party that controls the domain also controls the Nostr key used for the app registration. For OAuth wallet connections, that is still meaningful because redirect URI phishing and app impersonation are real risks.

A careful UMA Auth implementation should make this visible to the user. It should not show only a pretty logo. It should let the user recognize the app name, domain, requested commands and budget. If the permission screen hides the domain and NIP-05 context, the user loses one of the main checks the protocol provides.

The NWC side is still NIP-47

UMA Auth extends NWC, but it does not erase NIP-47. NIP-47 defines the remote wallet pattern: a client can access a Lightning wallet service through Nostr relays using encrypted request and response events. The NWC site describes the broader value in practical terms: apps can orchestrate payments without touching funds.

The same wallet-connection risks apply. The relay may not read encrypted request bodies, but it can still see timing and routing metadata. The connection URI must be secret. The wallet service should allow scoped permissions and revocation. Clients should not reuse one broad connection for unrelated jobs. Wallets should expose a clear connection-management screen.

UMA Auth adds a nicer connection ritual and cross-currency semantics, but the app still ends up making NWC requests. A developer who does not understand NWC should not treat UMA Auth as a black box. The NWC method set, relay behavior, event encryption, error handling and permission model are still the operational core after OAuth finishes.

Commands, budgets and currency

UMA Auth becomes especially interesting around budgets. The client can ask for required and optional commands, plus a spending limit, currency and period. A user might approve a monthly budget in sats or in a fiat currency. The provider then has to enforce that budget while the client sends wallet requests.

The VASP OpenAPI documentation explains why currency conversion matters. The UMA NWC image can track connection budgets, but the main VASP server must provide conversion rates when the payment currency differs from the budget currency. Before a payment, the image can call `GET /budget_estimate`; after a payment, responses such as `pay_invoice` or UMA pay-to-address flows may need to include the amount deducted in the budget currency.

This is not a minor accounting detail. If a user approves a ten-dollar monthly budget and an app pays a BTC invoice, the system must decide how much of the dollar budget was consumed. The app UI should not flatten that into a vague approved state. It should show the budget currency, period, commands and remaining budget in terms the user understands.

The client SDK path

For app developers, the quick path is the UMA Auth client SDK. The docs say SDKs are provided for Android, iOS and web platforms, with the web examples centered on the connect button and an NWC requester. This is the path most apps should start with because it keeps the OAuth and NWC handshake close to the reference implementation.

The client still owns product decisions. Which commands are required? Which are optional? Is `get_balance` needed, or would that reveal more than the app needs? Does the app truly need `pay_invoice`, recurring backend payments or transaction history? What is the smallest budget that makes the product useful? These choices are not boilerplate; they are the user's permission boundary.

The backend-payment caveat deserves special attention. The docs describe cases where a client app backend initiates NWC payments, such as recurring subscriptions, but warns that connection data sent to the backend includes highly sensitive fields. Once that design is chosen, the app must encrypt secrets, control staff access, avoid logs and understand token rotation. A backend-held wallet capability is an infrastructure risk, not just a frontend convenience.

The manual client path

The manual client implementation guide exists for teams that need more control. It walks through discovering the UMA provider configuration, building the authorization URL, handling the redirect, exchanging the code and making NWC requests without hiding the protocol behind the SDK. That can be useful for auditing or nonstandard platforms.

Manual implementation also increases the number of places to make a security mistake. The provider discovery document at `/.well-known/uma-configuration` can include endpoints and supported features. The authorization request needs the correct client identity, relay, redirect URI, code challenge, state, commands, budget and expiry. Any mismatch can become a broken connection or a security bug.

If you implement manually, test like a wallet engineer. Verify state handling, PKCE behavior, redirect URI matching, token exchange, token refresh, expired connection behavior, relay failures, insufficient budget, unsupported commands and revocation. A manual implementation should earn trust by being more transparent, not by skipping the reference guardrails.

The VASP side of UMA Auth

On the provider side, UMA Auth is a VASP integration project. The quick-start docs describe five steps: implement the UMA Auth OpenAPI schema, configure and run the UMA NWC Docker image, implement the token exchange, update the UMA configuration document and test the flow. That is a bigger commitment than adding a button to a website.

The VASP OpenAPI page describes the API as a RESTful interface used by the NWC image to communicate with the main VASP server. The minimum useful endpoints overlap with existing UMA work: look up an address, fetch a quote, execute a quote and combine those actions into a payment flow. Additional endpoints support invoices, keysend, balances, transaction lists, lookup and budget estimates.

The point is to separate roles. The NWC image can handle Nostr communication, connection setup, budget tracking and management UI. The VASP server still owns user accounts, money movement, currency conversion, compliance obligations and wallet state. If the VASP treats the Docker image as a magic outsourced wallet layer, the architecture will be misunderstood.

The UMA NWC Docker image

The UMA NWC Docker image is the reference operational shortcut for VASPs. The docs say it handles Nostr Wallet Connect communication, budget management, connection setup and the management UI, and can be configured with environment variables for branding, database storage, supported commands and more. The image is published through GitHub Container Registry as `ghcr.io/uma-universal-money-address/uma-nwc-server`.

The source repository, `uma-nwc-server`, describes a Nostr Wallet Connect server for UMA VASPs built with Quart, OpenAPI, SQLAlchemy and Alembic, with frontend code in the same repository. Checked on June 13, 2026, the public repository showed a small Apache-2.0 codebase with one tagged release line and active development history rather than a large multi-implementation ecosystem.

That size is not automatically a problem, but it changes the review posture. A VASP should pin image versions, read release notes, inspect configuration, protect the database, secure environment variables, choose relays deliberately and test upgrades before production. A wallet-facing Docker image deserves the same discipline as any other payment system component.

Token exchange and API isolation

The token-exchange guide makes an important boundary clear: the `uma-nwc-server` image does not have its own user database or authentication system. It relies on the VASP's existing login flow. A short-lived JWT from that flow is exchanged for longer-lived tokens that the NWC server can use for a particular connection.

This is good architecture only if the VASP respects the boundary. The main user login remains the VASP's responsibility. The NWC server gets enough authority to satisfy approved wallet requests. JWT scopes can be used to mirror approved commands. The OpenAPI docs also note that the API can often be limited to internal network access when the NWC image and VASP server live in the same private environment.

Readers should translate that into deployment checks. Is the UMA Auth API public or internal? Are long-lived tokens scoped? Are approved commands enforced in both the NWC image and the VASP backend? Are refresh tokens rotated and stored securely? Are budget and currency calculations auditable? The answer should be written down before real users connect wallets.

Relays and app registration visibility

Nostr relays appear twice in UMA Auth. First, the app registration event needs relays where providers can find the app identity. Second, NWC communication uses relay infrastructure to move encrypted wallet requests and responses. Those roles are related but not identical, and they should be chosen for reliability and visibility.

The app registration guide recommends public, well-known and reputable relays for the registration event. That makes sense because a provider checking the app identity needs to discover the event. For wallet requests, the relay choice affects latency, availability, metadata exposure and failure modes. A relay outage can look like a wallet outage if the app does not report it clearly.

A good UX should separate these failures. If the provider cannot verify the app registration, that is an identity problem. If the app has a valid connection but cannot send a request through the relay, that is a transport problem. If the VASP rejects a command, that is a permission or backend problem. Users and support teams need those distinctions.

What users should check

A user does not need to read every YAML file before clicking an UMA Auth button, but they should know what they are approving. Check the wallet provider, app name, app domain, requested commands, spending budget, budget period and revocation path. If the app asks for payment authority but gives no reason or budget, do not approve it.

Start with a small budget and a short period. UMA Auth can be powerful because it lets a favorite app initiate payments in the background or inside its own workflow. That same power is the risk. The safe default is one app, one connection, narrow commands, low budget, clear expiry and a test payment before meaningful use.

After connecting, find the provider's connection-management screen. Confirm the app appears there. Revoke it and prove that the app can no longer make requests. Then create a new connection for real use. This sounds fussy, but it is the fastest way to learn whether the provider gives you practical control or only a pretty approval screen.

What developers should check

Developers should treat UMA Auth as a wallet-permission system, not a sign-in badge. Store the NWC URI and tokens like secrets. Do not put them in browser logs, analytics events, crash reports, support screenshots or plaintext database fields. If backend payments are needed, encrypt the connection data and restrict operational access.

Request the smallest useful permission set. A tipping app may not need transaction history. A subscription app may not need direct balance visibility. A checkout app may need `pay_invoice` or pay-to-address behavior, but not broad read access forever. The protocol gives you command-level permissions; use them to reduce user risk.

Test all lifecycle edges: provider discovery, app identity lookup, NIP-05 verification, PKCE, redirect state, token expiry, refresh, rotated tokens, expired NWC connection, revoked connection, budget exhausted, currency conversion, unsupported wallet method, relay timeout and duplicate payment protection. The happy path is not enough when the output of the flow can spend money.

Where it fits beside plain NWC

Plain NWC is already useful. A wallet service can create a connection URI, an app can scan or paste it, and encrypted Nostr events can carry wallet requests. UMA Auth adds a discovery and approval layer for UMA-enabled wallets, plus cross-currency semantics that matter when the user thinks in dollars, euros or another local currency instead of only sats.

That means UMA Auth is not a replacement for all NWC. If you run Alby Hub, LNbits, LN Link or another NWC service, a simple connection URI may be the right tool. If your product specifically wants UMA wallet providers, recognizable OAuth permission screens, app registration events and currency-aware budgets, UMA Auth becomes relevant.

The best comparison is not which name sounds more advanced. Ask which user problem you have. For a developer testing a local wallet service, plain NWC may be simpler. For a mainstream app asking a hosted UMA wallet to approve scoped payment ability, UMA Auth may give users a more understandable and revocable connection flow.

The current public footprint

UMA Auth has a compact but well-defined public footprint. The docs live on docs.uma.me, the protocol extension is in the `uma-universal-money-address/protocol` repository, the OpenAPI schema has its own `uma-auth-api` repository, the Docker server lives in `uma-nwc-server`, and the app-registration CLI lives in `uma-auth-cli`. The SDK ecosystem includes language repositories such as JavaScript, Go, Python and Kotlin.

GitHub metadata checked on June 13, 2026 showed the protocol repository as the source-of-truth protocol definition with an Apache-2.0 license and recent 2026 activity. The UMA Auth API and CLI repositories were smaller. The `uma-nwc-server` repository had a v0.1.0 release from October 2024 and a Python/TypeScript split. This looks like an implementation family around a young extension, not a decades-old payment standard.

That should lead to practical caution, not dismissal. Young protocol extensions can be valuable when they solve a real integration problem. They also need version checks, provider-specific testing and clear fallbacks. Do not assume every UMA provider supports every method just because the docs list the shape of the system.

How to test an UMA Auth integration

Start with identity. Generate or inspect the app identity keypair, publish the kind 13195 registration event to known relays, verify the NIP-05 domain and confirm redirect URIs match exactly. Then run the client flow against a test UMA wallet or test VASP and verify that the permission screen shows the expected app name, image, domain, commands and budget.

Next test wallet behavior with tiny value. Ask for `get_info`, `get_budget` and `get_balance` only if approved. Make a small invoice or payment depending on the supported commands. Test a payment in a different currency from the budget if the provider claims cross-currency support. Confirm the remaining budget changes as expected and that transaction history is not exposed unless approved.

Finally test failure and cleanup. Let a token expire and refresh it. Revoke the connection and confirm requests fail. Exhaust the budget. Break relay connectivity. Send an unsupported command. Rotate backend tokens if the app uses server-side requests. A test plan that does not include revocation and failure is not finished.

The bottom line

UMA Auth is one of the more serious NWC-adjacent ideas because it aims at the onboarding problem. NWC can be powerful but awkward when a normal user has to copy a connection URI and understand wallet permissions. UMA Auth puts an OAuth-shaped permission flow in front of an NWC capability and adds UMA's money-address and cross-currency context.

That is useful only when the boundaries stay visible. The app has a Nostr identity. The provider authenticates the user. The connection grants commands and budget. The NWC URI and tokens are secrets. The VASP side may run a Docker image that enforces budgets and talks to the main payment backend. The relay moves encrypted requests, but it is still part of reliability and metadata posture.

Use UMA Auth when the product really needs an UMA-enabled wallet connection and can protect the capability it receives. Keep budgets low at first, verify app identity, read the provider's connection screen, test revocation, and treat backend-held tokens like payment credentials. When those pieces are handled, UMA Auth can make wallet-connected apps feel less brittle. Without them, OAuth polish can hide a connection that is more powerful than the user realizes.

Sources worth opening

Open the UMA Auth introduction and UMAD-01 spec first. Then read the client quick start, app registration guide, VASP OpenAPI page, Docker image page, token-exchange guide, uma-nwc-server repository, NIP-47 and OAuth/PKCE references. UMA Auth only makes sense when you see both halves: the friendly OAuth entry point and the wallet capability that comes out of it.