- Use Cases
- Use Case 10: Passwordless Authentication Integration
Use Cases
Use Case 10: Passwordless Authentication Integration
Generate passwordless authentication tokens so your users can access Remitian from your application.
Enable your users (taxpayers or firm users) to access Remitian’s platform seamlessly from your application. Generate passwordless authentication on behalf of your users and use it to provide direct access to Remitian’s features.
Understanding Passwordless Authentication
Passwordless authentication allows you to generate a temporary authentication token on behalf of a user (taxpayer or firm user) in your system. When your users need to access Remitian features, you can either embed Remitian in an iframe within your platform or redirect them to Remitian’s platform using the generated token for automatic authentication.
Use Cases:
- Embed Remitian’s platform within your application using an iframe
- Redirect users from your platform to Remitian with automatic login
- Allow taxpayers to view and manage their tax payments
- Allow firm users to access client management features
- Provide direct access to specific features (payment schedules, tax forms, etc.)
Token Characteristics:
- Single-use by default; can be made reusable until it expires by sending
oneTimeUse: false - Time-limited validity (15 minutes by default, configurable with the
expirationMinutesoption up to a maximum of 24 hours) - Bound to specific user account
- By default, the user must already have two-factor authentication set up to confirm the token; confirmation is rejected otherwise. The
skipMfaCodeoption lifts both the MFA prompt and this requirement, for trusted, server-initiated widget flows
Getting the User ID:
You can obtain the userId from:
- See Create a Taxpayer scenario - Use the
userIdfield in the 201 response - See Create a Firm User scenario - Use the
userIdfield in the 201 response - See List Taxpayers scenario - Use the
taxpayerUser.user.idfield - See List Firm Users scenario - Use the
user.idfield
Generate Passwordless Authentication
Sequence of Events:
- Your user (taxpayer or firm user) needs to access Remitian from your platform
- Your system retrieves the user’s
userIdfrom the List Taxpayers or List Firm Users endpoint - Your application (frontend or backend) calls Remitian API to generate a passwordless authentication for that user
- Remitian responds with a temporary authentication token
- Your application either embeds Remitian in an iframe or redirects to Remitian using the token URL
- User accesses Remitian and may be prompted to:
- Complete signup flow (if first-time user)
- Enter MFA code (if multi-factor authentication is enabled)
- No password required
HTTP Request:
POST https://public-api.remitian.com/v1/auth/users/{userId}/passwordless-authentications
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY
{
"oneTimeUse": false,
"expirationMinutes": 15,
"skipMfaCode": false
}
Request Body (optional):
The request body is optional. When omitted, the defaults below are applied.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
oneTimeUse | boolean | No | true | When true, the token is invalidated after its first successful use. When false, the token can be reused until it expires. |
expirationMinutes | integer | No | 15 | Token validity in minutes. Must be greater than 0 and at most 1440 (24 hours). |
skipMfaCode | boolean | No | false | By default, confirming the token requires the user to already have two-factor authentication set up, and prompts for the MFA code; users without 2FA are rejected. When true, confirmation skips both the prompt and that requirement, even for users with 2FA enabled. Intended for trusted, server-initiated widget flows only. Recommended to keep the default single-use behavior and a short expirationMinutes. |
Recommended usage: By default, tokens are single-use for security. For a continuous session experience, where the same token remains valid until it expires (for example, when embedding Remitian in an iframe that may reload), send oneTimeUse: false explicitly, as shown in the example above.
HTTP Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"token": "3f354c5c-aa4b-4da3-b127-db1616d461d4",
"status": "Pending",
"nextStep": "Confirmation",
"expiresAtUtc": "2026-08-17T18:45:00Z",
"oneTimeUse": false,
"skipMfaCode": false
}
Access Remitian Platform
Sequence of Events:
- After receiving the token, construct the Remitian URL with the token and optional redirect URL parameters
- Either embed Remitian in an iframe within your application or redirect the user to Remitian
- Navigate to the constructed URL with the token
- User authenticates without entering a password
What Users Will Experience:
- First-time users: Will be prompted to complete the signup process
- Existing users: Will be prompted to enter their MFA code
- Users authenticated with
skipMfaCode: true: Will NOT be prompted for an MFA code, even if two-factor authentication is enabled - All users: Will NOT be asked to enter a password
URL Format:
The URL format varies by environment:
# Production
https://app.remitian.com/auth-passwordless?token={token}&redirectUrl={optional_redirect_url}
# Sandbox
https://app.sandbox.remitian.com/auth-passwordless?token={token}&redirectUrl={optional_redirect_url}
For CA customers, use the .ca domain: https://app.remitian.ca in Production and https://app.sandbox.remitian.ca in Sandbox.
Parameters:
| Parameter | Required | Description |
|---|---|---|
token | Yes | The passwordless authentication token from the previous step |
redirectUrl | No | Optional URL to redirect to after successful authentication Example: /taxpayers/123/payments |
Example URLs:
# Production
https://app.remitian.com/auth-passwordless?token=3f354c5c-aa4b-4da3-b127-db1616d461d4&redirectUrl=/dashboard
# Sandbox
https://app.sandbox.remitian.com/auth-passwordless?token=3f354c5c-aa4b-4da3-b127-db1616d461d4&redirectUrl=/dashboard
Implementation Example (JavaScript):
The recommended way to embed Remitian in your application is the Widget Library via our JavaScript SDK. Each widget opens as a modal in your application, authenticated with the passwordless token generated in the previous step.
import * as Remitian from '@remitian/widget-sdk';
// Step 1: Request passwordless authentication from your backend
// (always generate the token server-side to protect your API credentials)
async function getPasswordlessAuthentication(userId) {
const response = await fetch(`/api/remitian/passwordless-authentication/${userId}`, {
method: 'POST'
});
const data = await response.json();
return data.token;
}
// Step 2: Create and open the widget with the token
async function openRemitianWidget(userId, environment = 'production') {
const token = await getPasswordlessAuthentication(userId);
const widget = Remitian.create(
Remitian.buildPayAllConfig({
passwordlessToken: token, // optional; omit to let the user log in
environment, // 'sandbox' | 'production' (default)
taxEntity: { externalId: 'my_tax_entity_123' },
onSuccess: (result) => {}, // approved payments only
onError: (error) => {}, // failed payments only
onExit: (reason) => {}, // never a success signal
}),
);
widget.open();
}
Security Considerations:
- Tokens are single-use and expire after 15 minutes by default; when opting into reusable tokens (
oneTimeUse: false), keep the expiration as short as your session flow allows - Always generate tokens server-side to protect your API credentials
- Use HTTPS for all communications
- Validate user identity before generating tokens
- Consider implementing additional redirect URL validation
- A
skipMfaCode: truetoken is a bearer credential that grants access without a second factor: generate it server-side only, keep the default single-use behavior (do not sendoneTimeUse: false), and use a shortexpirationMinutesto limit its exposure window