Skip to main content
Some Etherfuse flows run inside the app, not over the API: the user completes them in their browser, in a real authenticated session. You send a user into one with a launch: sign a short-lived user JWT carrying the flow’s scope, then have the user’s browser hand it to /auth/launch with the flow’s target. The launch mechanism is identical for every flow and is documented once in JWT User Authentication. Only the scope and target change between flows; the full list is below.

​
Scopes

The scope claim is required on every partner JWT and names what the user may do. It is strictly enforced: the claim cannot be omitted, and any value other than a scope listed below is rejected with invalid_scope. Ask only for the scope a user needs.

​
Targets

The target is the app path the launch lands the user on. It must be one of the paths listed below, optionally with a query string (for example ?org=<org_id>, used by Business KYB). Any other path, or an absolute URL, is rejected with invalid_target, so a launch can’t be redirected off-site.

​
Flows

FlowscopetargetWhat the user does
Sign agreementsagreements/agreementsReviews and signs the three required agreements (electronic signature, terms and conditions, customer agreement).
Identity verificationverification/idv?bank_account_id=<uuid>Per-bank verification for a non-compliant bank — a liveness face scan matched against the ID already on file. Append &lang=es for Spanish.
Business KYBkyb/kybCompletes Know Your Business verification for a business.
A launch’s JWT needs the matching scope, and the target must be the matching path.

​
Sign agreements

scope: agreements · target: /agreements Signing the required agreements (electronic signature, terms and conditions, and customer agreement) is a mandatory step in customer onboarding. Etherfuse’s fully hosted KYC onboarding handles it for you; if you run KYC programmatically, this launch is how you complete the agreements step: send the customer into /agreements to review and sign them in a real session.
Submit the customer’s KYC identity first. The customer agreement is generated from their identity (name, address, email), so submit it, for example via POST /ramp/customer/{id}/kyc, or let them fill any missing fields on the signing page. See Customer Onboarding (KYC). In sandbox, the customer is auto-approved once all three agreements are signed.

​
Identity verification

scope: verification · target: /idv?bank_account_id=<uuid> This is a per-bank verification step — not part of org approval (KYC/KYB). Some bank accounts require additional compliance when they’re registered; today that’s Mexican (SPEI) bank accounts. The contract is simple: after you register a bank, check its compliant flag — if it comes back compliant: false, launch the customer here to verify that bank; if it’s compliant: true, this step is unnecessary. Don’t assume which banks need it — just react to compliant. Pass the bank in the launch target: /idv?bank_account_id=<uuid> (required). The launched user must administer the org that owns the bank. The customer completes a liveness face scan, which nero matches against the ID they already submitted during KYC. Append &lang=es to render the entire flow in Spanish (all UI text, face scan prompts, error messages, and status screens). Omit the parameter or pass lang=en for English. Example: /idv?bank_account_id=<uuid>&lang=es.
The customer must have completed KYC first. /idv reuses the ID document already on file and captures a live selfie to match against it; it does not collect the ID again. If no ID is on file, the page tells the customer to finish identity verification before continuing. This gates only the bank, not the organization: a compliant: true bank needs nothing, and the page reports “nothing to verify” if you launch it for one.
Camera access. The face scan needs the camera. If you embed the launch in an iframe, the iframe element must delegate camera access with a wildcard origin: allow="camera *; microphone *". The bare form (allow="camera") only grants the camera to the iframe’s own src origin, but the scan SDK uses it from a nested frame, so without the * the browser blocks the camera and the scan never starts. A top-level tab or popup needs nothing extra.

​
Business KYB

scope: kyb · target: /kyb Use to send a user into Know Your Business verification. Append ?org=<org_id> to the target to choose which organization to verify; without it, the app uses their current org or prompts them to create a business. See the KYB guide for the full walkthrough.