OAuth Details for Client Applications
Before making an NWC request, verify that your OAuth token is still valid by checking its expiration. You can get the
expiration timestamp by adding the
expires_in
value from the OAuth response to the token creation timestamp. Note
that the client app SDKs already do this, so if you are using the SDK, you don't need to worry about token expiration
and can skip this section. If your token is expired, you will have to refresh it using the standard OAuth 2.0 flow.First, you'll fetch your user's wallet Configuration Document
from the
/.well-known/uma-configuration
path. For example, if your user's UMA address is
<username>@coolvasp.net
, you would make a GET
request to https://coolvasp.net/.well-known/uma-configuration
.
This is JSON document contains the OAuth token endpoint.Next, you'll make a POST request to this token endpoint. The
refresh_token
parameter below is the refresh token from
your previous OAuth token response, and the client_id
parameter is your application's unique identifier, in the format
"appIdentityPubkey nostrRelayUrl"
where appIdentityPubkey
is public key from your App Identity keypair and the nostrRelayUrl
is the url of the relay on which your App Registration event is published.POST /oauth/token HTTP/1.1
Host: https://nwc.coolvasp.net
grant_type=refresh_token
&refresh_token=IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk
&client_id=npub16f80k0f4vg0nnlepxrqxeh81slyzst2d%20wss://myrelay.info
If successful, the user's wallet will respond as follows:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token":"b9d11fe05e266fe7389fdf1359211e7859656a7898d64f3066092156de109b31",
"token_type":"Bearer",
"expires_in":86400,
"refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTDk",
"nwc_connection_uri": "nostr+walletconnect://a421a5e2a615eff3b797be5318e4e187d24b100748cfaa8d0b390ce659906d8f?relay=wss://relay.getalby.com/v1&secret=b9d11fe05e266fe7389fdf1359211e7859656a7898d64f3066092156de109b31&lud16=$bob@examplevasp.com"
"commands": ["get_budget", "pay_invoice", "fetch_quote", "make_invoice", "get_balance", "get_info", "pay_keysend", "lookup_user", "pay_to_address", "execute_quote"],
"budget": "100.USD/month",
"nwc_expires_at": 1721796505
}
You should persist this response as your new OAuth state, the previous state is now invalid. Now that the token
is valid, you may continue making NWC requests for this connection. Note that the refresh token also rotates on
every refresh, so make sure to update that too if you're not using the client SDK.
Connections expire after a time period which is configurable by the user. You should check if the connection is expired before using it to make
an NWC request. You may do so by checking the
nwc_expires_at
field on the OAuth response. You will receive an UNAUTHENTICATED
error if you
make an NWC request using a connection which is no longer valid. Once a connection is expired, you will need to prompt the user to extend the
expiration period of the connection in their wallet's UI or establish a new connection in your client application.The Client App SDKs will change UI state based on whether there is an active, non-expired connection. In the event that your user's connection expires,
the UMA button UI will change to the pending connection state, and users can go through the OAuth flow again to establish a new connection. If you are
making NWC requests from your backend, you may choose to notify users in advance of impending expirations, so they can take action.