Seamless OAuth

Seamless OAuth allows your users to access Melio's features without leaving your application or going through a separate authentication flow. Instead of redirecting users to Melio's login page, your application handles the authentication and provides Melio with the necessary tokens to identify and onboard users automatically.

OAuth Flow Overview

Standard OAuth Flow

The following diagram shows how a typical OAuth flow would work between Melio and your application:

• Request authorization:
  • User requests the Partner app to open Melio - the partner app directs the user to open Melio's EmbedUrl
  • Melio returns the user back to the InitiateAuthorizationUrl with response_type=code and additional OAuth flow parameters (such as client_id, scope, etc...)
• Authorization flow:
  • Partner Api generates an authorization_code and connects it with the currently logged in user
  • Partner Api redirects to melio's EmbedUrl with the authorization_code
  • Melio Api calls Partner Api's TokenExchangeEndpoint with the authorization_code from above along with the client_secret and any other parameter provided.
  • The partner api responds with an access_token that can be used to access AccountInfo and additional endpoints.
• Data Exchange flow:
  • Melio calls the partner's AccountInfoEndpoint with the access_token to get user and company info
  • Melio registers and authenticates the user and starts the experience.

Availability

A full OAuth workflow is only available for redirect embedding. For hosted embedding only the simplified OAuth flow, JWE and link authentication are available

Simplified OAuth Flow (Recommended)

Since the partner application is initiating the request and the user is already authenticated within the system, there is no additional security benefit in performing the full authorization request flow. We can streamline the user experience by skipping the authorization steps and performing the token exchange directly.

The following is a simplified OAuth flow:

This simplified flow reduces the number of redirects and gets users into the Melio application faster while maintaining the same security posture.

Implementation Steps

1. Configure Partner Portal Settings

First, configure the endpoints that Melio needs to call to authenticate users and retrieve account information.

1. Log in to the Partner Portal using the credentials provided to you
2. Go to the SSO configuration section and configure:
   • Token endpoint URL: Your OAuth 2.0 token endpoint
   • Additional properties: Any extra parameters to send (typically client_id, client_secret, and scope)
   • Account info URL: Your server endpoint to get user account information
   • Funding sources URL (optional): Endpoint to retrieve pre-existing bank accounts
3. Go to the App settings section and retrieve your partnerName

2. Implement Token Exchange Endpoint

Create an endpoint that follows the OAuth 2.0 specification to exchange authorization codes for access tokens.

Endpoint Requirements:

• Method: POST
• Content-Type: application/json or application/x-www-form-urlencoded
• Response: JSON with access_token (and optionally expires_in, refresh_token)

Request Payload:

Property	Required	Description
code	Yes	The authorization code provided to Melio's auth URL
client_id	No	Client ID for OAuth integration (if configured)
client_secret	No	Client secret for OAuth integration (if configured)
scope	No	OAuth scope (if configured)
grant_type	Yes	Always "authorization_code"

Example Response:

{
	"access_token": "238beab2-b545-4fee-80fa-63f224bc56f6",
	"token_type": "Bearer",
	"expires_in": 900
}

3. Implement Account Information Endpoint

Create an endpoint that returns user and company information for the authenticated user.

Endpoint Requirements:

• Method: GET
• Authorization: Bearer token in header
• Response: JSON with user and company data

Required Response Fields:

Property	Required	Description
user.id	Yes	Unique user identifier in your system
user.email	Yes	User's email address
user.firstName	Yes*	User's first name
user.lastName	Yes*	User's last name
user.phone	Yes*	User's phone number (US format)
user.dateOfBirth	Yes*	User's date of birth (YYYY-MM-DD, must be 18+ years old)
company.id	Yes	Unique company identifier in your system
company.name	Yes*	Business name
company.address	Yes*	Business address object
company.legalAddress	Yes*	Business legal address object

*Will be collected by Melio if not provided

Example Response:

{
	"user": {
		"id": "us142664",
		"email": "john.doe@example.com",
		"firstName": "John",
		"lastName": "Doe",
		"phone": "+1-555-123-4567",
		"dateOfBirth": "1985-03-15"
	},
	"company": {
		"id": "ac51512",
		"name": "Acme Corporation",
		"legalName": "Acme Corporation LLC",
		"phoneNumber": "+1-555-987-6543",
		"businessType": "LLC",
		"address": {
			"state": "CA",
			"line1": "123 Main Street",
			"city": "San Francisco",
			"postalCode": "94105"
		},
		"legalAddress": {
			"state": "CA",
			"line1": "123 Main Street",
			"city": "San Francisco",
			"postalCode": "94105"
		},
		"taxInfo": {
			"identifier": "12-3456789",
			"type": "EIN"
		},
		"industry": {
			"naicsCode": 722511,
			"name": "Full-Service Restaurants"
		}
	}
}

4. Generate Authorization Codes

Your application needs to generate OAuth authorization codes when users want to access Melio.

5. Use the token for authentication

Pass the generated authorization code to the melio auth-url

Error Handling

If authentication fails, Melio will:

1. Display an error screen to the user
2. Post an AUTHENTICATION_ERROR message to the parent application
3. Provide error details for debugging

Make sure your endpoints return appropriate HTTP status codes and error messages for troubleshooting.