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.