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

# Create a token to initialize the Benji Connect SDK

> Create a token to initialize an instance of the Benji Connect SDK or Benji Hosted Connect.

<Note>
  The `x-api-key` header value to be used on this API is your **partner API
  key**, which can be generated through the [Developer](/pilot/developer) page
  in Pilot.
</Note>

<Note>
  The Connect Token API resolves **merchant** and **partner** from
  **`partnership_id`**.
</Note>

### Request body

<ParamField body="partnership_id" type="string" required>
  The unique identifier of the partnership on the Benji Platform.
</ParamField>

<ParamField body="mode" type="number" required>
  The connection mode for the SDK (Connect = 1, Transfer = 3, and Redeem = 4).
  See [Connect modes](/connect/modes).
</ParamField>

<ParamField body="display_name" type="string">
  Display name shown in the Connect UI. If omitted, the name configured for the
  partnership on the platform is used.
</ParamField>

<ParamField body="user_external_id" type="string">
  A unique identifier for the user in your system. When set, the flow can skip
  the authentication step for your user.
</ParamField>

<ParamField body="custom_attributes" type="object" optional>
  Custom attributes for the connection flow (e.g. transfer actions).

  <Expandable title="properties" defaultOpen="true">
    <ParamField body="actions" type="array" optional>
      Array of actions (e.g. transfer amounts).

      <Expandable title="action properties" defaultOpen="true">
        <ParamField body="mode" type="number" optional>
          Action mode: **Transfer = 3**
        </ParamField>

        <ParamField body="amount" type="number" optional>
          Preselected points amount for action.
        </ParamField>

        <ParamField body="allows_editing" type="boolean" optional>
          Whether the user can edit the amount in the UI.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Example requests

<AccordionGroup>
  <Accordion title="Minimal request (Connect mode)">
    ```json theme={null}
    {
        "partnership_id": 49,
        "mode": 1,
        "display_name": "Reward Cookies"
    }
    ```
  </Accordion>

  <Accordion title="With user_external_id">
    ```json theme={null}
    {
        "partnership_id": 49,
        "mode": 1,
        "display_name": "Reward Cookies",
        "user_external_id": "user-1234"
    }
    ```
  </Accordion>

  <Accordion title="Transfer mode (mode 3) with custom_attributes">
    ```json theme={null}
    {
        "partnership_id": 49,
        "mode": 3,
        "display_name": "Reward Cookies",
        "custom_attributes": {
            "actions": [
                {
                    "mode": 3,
                    "amount": 1000,
                    "allows_editing": true
                }
            ]
        }
    }
    ```
  </Accordion>

  <Accordion title="Redeem mode (mode 4)">
    ```json theme={null}
    {
        "partnership_id": 49,
        "mode": 4,
        "display_name": "Reward Cookies"
    }
    ```
  </Accordion>
</AccordionGroup>

### Return values

<ResponseField name="token" type="string" required>
  The connect token to pass when [initializing the Benji Connect
  SDK](/connect/initialization) or as `connect_token` on the [**Benji Hosted
  Connect**](/connect/hosted/introduction) URL.
</ResponseField>

<ResponseField name="connect_url" type="string">
  Base URL for **Benji Hosted Connect** for this partnership. Append `?connect_token=<token>` (and optional query parameters) to send users into **Benji Hosted Connect**. May be empty if **Benji Hosted Connect** URLs are not enabled for your account.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
      "code": "ok",
      "data": {
          "token": "0c371a1c-aa81-11ef-b28c-0a58a9feac02",
          "connect_url": "https://connect.withbenji.com/khkgfoud76td"
      }
  }
  ```

  ```json 401 theme={null}
  {
    "error": "unauthorized_partner",
    "message": "Invalid key, or key is not authorized to make this call"
  }
  ```

  ```json 500 theme={null}
  {
    "error": "unexpected_error",
    "message": "An unexpected error has occurred"
  }
  ```
</ResponseExample>