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

# Connect user

Initiate a connection between a user and your application. This is how you get a per-user api-key.

Requires your **master api-key**. [HMAC signing](/authentication/hmac-signing) required if `callback` is provided.

<ParamField body="email" type="string" required>
  The user's email address
</ParamField>

<ParamField body="callback" type="string">
  Webhook URL where we send the api-key and status updates. Requires HMAC.
</ParamField>

<ParamField body="ref" type="string">
  Your internal user ID. Returned in all webhooks so you can match them.
</ParamField>

<ParamField body="direction" type="string">
  `FIAT_TO_CRYPTO` or `CRYPTO_TO_FIAT`. Pass this to create a connection in the same call.
</ParamField>

<ParamField body="btcAddress" type="string">
  BTC address (26-90 chars). Required if `direction` is `FIAT_TO_CRYPTO`.
</ParamField>

<ParamField body="iban" type="string">
  Valid IBAN. Required if `direction` is `CRYPTO_TO_FIAT`.
</ParamField>

<ParamField body="bic" type="string">
  BIC/SWIFT code (8-11 chars).
</ParamField>

<ParamField body="beneficiaryName" type="string">
  Account holder name (2-100 chars).
</ParamField>

<ParamField body="lnAddress" type="string">
  Lightning address for LN sell connections.
</ParamField>

<ParamField body="currency" type="string">
  `BTC`, `ETH`, `USDC`, or `USDT`. Default: `BTC`.
</ParamField>

<ParamField body="network" type="string">
  Blockchain network. Default: `BTC`.
</ParamField>

<ResponseExample>
  ```json User already connected (200) theme={null}
  {
    "status": "connected",
    "userRegistered": true,
    "isUserConnected": true,
    "apiKey": "NzY1YWQzZGYwNTE4NDQ4NzkxMTcxMTIxYzVmY2NlMDI="
  }
  ```

  ```json Existing user, not connected (200) theme={null}
  {
    "status": "pending",
    "userRegistered": true,
    "isUserConnected": false
  }
  ```

  ```json New user (200) theme={null}
  {
    "status": "onboarding",
    "userRegistered": false,
    "isUserConnected": false,
    "signupURL": "https://app.bringin.xyz/signup?inviteId=..."
  }
  ```
</ResponseExample>