> ## Documentation Index
> Fetch the complete documentation index at: https://docs.etherfuse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Launch a user into the app

> > ⚠️ **Different host.** Unlike every other endpoint in this reference, `/auth/launch` lives on the **app host** (`app.etherfuse.com` / `sandbox.etherfuse.com`), **not** the API host (`api.etherfuse.com`). It is a browser-facing page, not a JSON API.

Drops one of your users into the Etherfuse app with an authenticated session. Use it for **browser** flows, such as sending a user into KYB. Your server POSTs an HTML form (or redirects the browser) to this URL; the app establishes the session and redirects the user to `target`. To embed the flow in an iframe or popup instead, use the [postMessage variant](/api-reference/launch-via-postmessage).

## Targets

The `target` and `scope` for every flow you can launch a user into (and what to know about each) are documented in [User Launch Flows](/guides/user-launch-flows). A `target` must be one of those allowed paths (optionally with a query string such as `?org=<org_id>`); any other path is rejected with `invalid_target`.

The JWT's `sub` is _strongly recommended_ to be a UUID identifying the person signing in (see [Sign a user JWT](/guides/jwt-authentication#sign-a-user-jwt) for how `sub` relates to the Ramp API `customerId` for individuals vs businesses), and its `scope` follows the same rules as [`/auth/token`](/api-reference/authentication/exchange-a-partner-jwt). The endpoint is unauthenticated: the JWT or refresh token is the credential.

<RequestExample>
  ```html Form POST theme={null}
  <form id="launch" method="POST" action="https://sandbox.etherfuse.com/auth/launch">
    <input type="hidden" name="grant_type" value="urn:ietf:params:oauth:grant-type:jwt-bearer" />
    <input type="hidden" name="assertion" value="<your_signed_jwt>" />
    <input type="hidden" name="target" value="/kyb" />
  </form>
  <script>document.getElementById("launch").submit()</script>
  ```

  ```html Into an iframe theme={null}
  <iframe name="etherfuse"></iframe>

  <!-- target the iframe so the launch loads inside it -->
  <form method="POST" action="https://sandbox.etherfuse.com/auth/launch" target="etherfuse">
    <input type="hidden" name="grant_type" value="urn:ietf:params:oauth:grant-type:jwt-bearer" />
    <input type="hidden" name="assertion" value="<your_signed_jwt>" />
    <input type="hidden" name="target" value="/kyb" />
  </form>
  <script>document.forms[0].submit()</script>
  ```
</RequestExample>


## OpenAPI

````yaml POST /auth/launch
openapi: 3.1.0
info:
  title: Etherfuse FX API
  description: Partner-facing ramp API for onramps, offramps, swaps, and KYC.
  license:
    name: Proprietary
  version: 1.0.0
servers:
  - url: https://api.sand.etherfuse.com
    description: Sandbox
security:
  - ApiKeyAuth: []
tags:
  - name: Authentication
    description: >-
      Partner JWT authentication — exchange a JWT for an access token, or launch
      a user into the app.
  - name: Lookup
    description: >-
      Public reference data: exchange rates, stablebonds, bond costs, country
      codes.
  - name: Assets
    description: Rampable stablecoins and stablebonds available per blockchain.
  - name: Onboarding
    description: Hosted and programmatic customer onboarding.
  - name: Bank Accounts
    description: Register and retrieve customer bank accounts.
  - name: Quotes
    description: Price quotes for onramps, offramps, and swaps.
  - name: Orders
    description: Create, track, and manage ramp orders.
  - name: Swaps
    description: Crypto-to-crypto swaps.
  - name: Sponsored
    description: Token approvals for sponsored (gasless) offramps.
  - name: Customers
    description: Customer (child-organization) records.
  - name: Wallets
    description: Register and manage customer wallets.
  - name: KYC
    description: Submit and check customer KYC status.
  - name: Webhooks
    description: Event notification subscriptions.
  - name: Organizations
    description: Organization identity, child orgs, and partner fees.
paths:
  /auth/launch:
    servers:
      - url: https://sandbox.etherfuse.com
        description: Sandbox app (NOT the API host)
    post:
      tags:
        - Authentication
      summary: Launch a user into the app
      description: >-
        > ⚠️ **Different host.** Unlike every other endpoint in this reference,
        `/auth/launch` lives on the **app host** (`app.etherfuse.com` /
        `sandbox.etherfuse.com`), **not** the API host (`api.etherfuse.com`). It
        is a browser-facing page, not a JSON API.


        Drops one of your users into the Etherfuse app with an authenticated
        session. Use it for **browser** flows, such as sending a user into KYB.
        Your server POSTs an HTML form (or redirects the browser) to this URL;
        the app establishes the session and redirects the user to `target`. To
        embed the flow in an iframe or popup instead, use the [postMessage
        variant](/api-reference/launch-via-postmessage).


        ## Targets


        The `target` and `scope` for every flow you can launch a user into (and
        what to know about each) are documented in [User Launch
        Flows](/guides/user-launch-flows). A `target` must be one of those
        allowed paths (optionally with a query string such as `?org=<org_id>`);
        any other path is rejected with `invalid_target`.


        The JWT's `sub` is _strongly recommended_ to be a UUID identifying the
        person signing in (see [Sign a user
        JWT](/guides/jwt-authentication#sign-a-user-jwt) for how `sub` relates
        to the Ramp API `customerId` for individuals vs businesses), and its
        `scope` follows the same rules as
        [`/auth/token`](/api-reference/authentication/exchange-a-partner-jwt).
        The endpoint is unauthenticated: the JWT or refresh token is the
        credential.
      operationId: auth_launch
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AuthLaunchRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/AuthLaunchRequest'
      responses:
        '200':
          description: >-
            An HTML page that establishes the session and redirects the browser
            to `target`.
      security: []
components:
  schemas:
    AuthLaunchRequest:
      type: object
      required:
        - grant_type
        - target
      properties:
        grant_type:
          type: string
          enum:
            - urn:ietf:params:oauth:grant-type:jwt-bearer
            - refresh_token
        assertion:
          type: string
          description: >-
            The partner-signed JWT. Required when `grant_type` is
            `urn:ietf:params:oauth:grant-type:jwt-bearer`.
        refresh_token:
          type: string
          description: >-
            A `refresh_token` from a prior `POST /auth/token` exchange. Required
            when `grant_type` is `refresh_token`.
        target:
          type: string
          description: >-
            App path to land the user on after sign-in. Must be an allowed
            target. See [User Launch Flows](/guides/user-launch-flows#targets).
            Any other path is rejected.
          example: /kyb
        return_url:
          type: string
          description: Optional URL to return the user to when they leave the app.
      example:
        grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
        assertion: eyJhbGciOiJSUzI1NiIsImtpZCI6Imt...
        target: /kyb
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key sent in the Authorization header.

````