# Visa Platforms Login

## How to Use

This guide walks you through the standard workflow for Visa Platforms Login, from cardholder enrollment to successful program access and ongoing authentication.

- Review the Workflow Reference for comprehensive workflow guidance across all user types.
- Check Things to Know for business rules, guardrails, and user type considerations.
- Review Authentication Methods for specialized OAuth2 scope configuration.
- Consult Error Codes for product-specific error handling guidance.

### Choose Your Integration Path

Select the appropriate workflow based on your business requirements and user type.

| If You Want To | Use This Workflow | Key Requirements |
| --- | --- | --- |
| Enable standard user registration | Standard User Onboarding | Email validation capability, user password management |
| Implement frictionless consumer opt-in | Guest User Enrollment | CLIENT_ID header, OFAC screening compliance, message-level encryption (external) |
| Enable passwordless authentication | Passwordless Login | Email OTP delivery, domain validation |
| Migrate existing user data | Migration Operations | MIGRATE_USERS scope, batch processing capability |
| Provide customer service support | Concierge Operations | SYSTEM_USER_R scope, issuer site association |

### Standard User Onboarding Workflow

To successfully enroll cardholders into Visa programs, follow this specific sequence of API calls. This workflow represents the core business process from initial enrollment to successful program access.

**Step 1: User Registration**  
Create an account in the GMAP system. This API validates the users and sends an activation token via email.

- **Endpoint:**  `POST /user/registration`  
- **Requirement:** primaryUserIdentifier must be unique per site and tenant  
- **Key Fields:** email, primaryUserIdentifier, userSiteRegistrationRequest

**Step 2: Account Activation**  
Complete user account activation with activation token to complete registration. Account activation must complete before authentication attempts.

- **Endpoint:**  `POST /user/activate-token/{userId}`  
- **Requirement:** Valid activation_token from registration email  
- **Note:** Activation tokens expire and will return 404 if expired

**Step 3: User Authentication**  
Verify user credentials and authenticate for site access. Successful authentication indicates the integration is working correctly.

- **Endpoint:**  `POST /user/site/{siteId}/login`  
- **Key Parameters:** username, password (as array), siteId  
- **Optional:** deviceToken, otp, otpType, trustDevice for enhanced functionality

**Step 4: Profile Validation**  
Retrieve user profile to confirm successful integration and access to program features.

- **Endpoint:**  `GET /user/find`  
- **Success Indicator:** Returns userDetailsId, account status active, and complete profile information

### Guest User Enrollment Workflow

Enable frictionless consumer opt-in with validated data sharing through 1-click enrollment with no user involvement.

**Step 1: Guest Enrollment**  
Enroll user into GMAP with passwordless enrollment. Valid user accounts will be auto-activated after OFAC sanctions verification.

- **Internal Partner:**  `POST /user/v2/enrollments` with clientId header  
- **External Partner:**  `POST /user/external/guest/enrollments` (requires message-level encryption)  
- **Key Fields:** primaryUserIdentifier, site, externalSourceId, userSiteAttributes

**Step 2: Password Establishment**  
User receives notification to set password on the GMAP website. After enrollment, the user needs to reset password to obtain credentials for login.

- **Endpoint:**  `POST /user/change-password-from-passcode`  
- **Note:** Old password not needed for this request

**Step 3: Authenticated Access**  
User can now authenticate with established credentials.

- **Endpoint:**  `POST /user/site/{siteId}/login`

### How to Handle Password Reset

1. Send passcode or OTP to user via email or SMS using `POST /user/send-passcode`
2. Verify code validity using `POST /user/find-code`
3. Set new password using `POST /user/change-password-from-passcode`

### Common Tasks

#### How to Extend User Sessions

Sessions can be extended rather than requiring re-authentication.

1. Call `POST /user/extend-login` with valid user token.
2. Handle session extension failures (401 error indicates session cannot be extended).
3. Fall back to full authentication if extension fails.

#### How to Implement Multi-Factor Authentication

1. Ensure user is logged in and has NOT_ENROLLED MFA status.
2. Generate TOTP secret using `POST /user/mfa/totp/setup`.
3. User configures authenticator app with provided secret.
4. Complete enrollment using `POST /user/mfa/totp/enroll` with TOTP verification.

#### How to Manage User Aliases

1. Create or update login alias using `POST /user/alias`.
2. User can login with alias instead of primary identifier.
3. Delete alias when no longer needed using `POST /user/alias/delete`.

**Important:** User aliases must be unique within tenant scope.