Wallet Connection Flow

1. Authorization Request

Redirect the user to the authorization URL:

GET https://app.withreload.com/v1/oauth/authorize
	?client_id=YOUR_CLIENT_ID
	&redirect_uri=YOUR_REDIRECT_URI
	&response_type=code
	&scope=wallet:read wallet:write transactions:read
	&state=RANDOM_STATE_STRING

Parameters:

• client_id (required): Your application's client ID
• redirect_uri (required): The URI to redirect to after authorization
• response_type (required): Must be "code"
• scope (required): Space-separated list of requested scopes
• state (recommended): Random string to prevent CSRF attacks

2. User Authorization

The user will be prompted to log in (if not already) and authorize your application. After authorization, they will be redirected to your redirect URI with an authorization code..

https://your-app.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE_STRING

❗️

Important

Make sure to register the callback URL in the Reload developer page.

3. Code Exchange for Wallet Token

Exchange the authorization code for a wallet token::

POST https://app.withreload.com/v1/oauth/token
Content-Type: application/json
{
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "YOUR_REDIRECT_URI"
}

Response:

{
  "wallet_token": "WALLET_TOKEN",
  "token_type": "Bearer",
  "scope": "wallet:read wallet:write transactions:read"
}

4. Using the Wallet Token

The wallet token must be used together with your client credentials when calling the wallet APIs:

// API Request Headers
Authorization: Bearer WALLET_TOKEN
x-client-id: YOUR_CLIENT_ID
x-client-secret: YOUR_CLIENT_SECRET

Important Security Notes:

• The wallet token is bound to your application and can only be used with your client credentials.
• Even if the wallet token is compromised, it cannot be used by other applications.
• The wallet token has a very long expiry (10 years) and does not need to be refreshed.
• Your client credentials should be kept secure and never exposed in client-side code.

Composite Token Security

The composite token approach provides enhanced security by requiring both the wallet token and your client credentials for API access:

// API Request Headers
Authorization: Bearer WALLET_TOKEN
x-client-id: YOUR_CLIENT_ID
x-client-secret: YOUR_CLIENT_SECRET

Security benefits:

• The wallet token is bound to your application and cannot be used by other applications.
• Even if the wallet token is compromised, it's useless without your client credentials.
• Your client credentials are kept secure on your server and never exposed to clients.
• The wallet token has a very long expiry (10 years) and doesn't need to be refreshed.

Authorization Code Flow

We use the OAuth 2.0 authorization code flow for secure wallet token issuance:

• Secure token delivery: The wallet token is never exposed in browser history, URL parameters, or server logs.
• Server-to-server exchange: The authorization code is exchanged for a wallet token in a secure server-to-server request.
• Short-lived codes: Authorization codes are valid for only 10 minutes and can only be used once.
• Code binding: Each authorization code is bound to a specific client ID and redirect URI.

Security Considerations

• Store wallet tokens securely: Store wallet tokens securely in your database, preferably encrypted.
• Protect client credentials: Never expose your client secret in client-side code or public repositories.
• Validate redirect URIs: Only use redirect URIs that have been pre-registered in your application settings.
• Use state parameter: Always include a random state parameter to prevent CSRF attacks.
• Check connection status: Verify that the wallet is still connected before making API calls.
• Implement proper error handling: Handle authorization errors gracefully in your application.
• Use HTTPS: Always use HTTPS for all API requests and redirects.