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

# Authentication & account connections

> How your server authenticates, and how businesses connect their Broco accounts to your platform.

Two things identify a request: your integration and the Broco account involved. Your integration authenticates with a secret. The account is always linked through a connection that its owner authorized.

## Integration secret

Broco issues an integration secret to your platform. It authenticates every server-to-server request.

```bash Request header theme={null}
Authorization: Bearer $BROCO_SECRET_KEY
```

<Warning>
  Keep the secret on your server. Never send it to a browser, a mobile app or a carrier's device.
</Warning>

The secret identifies your integration. It does not authorize spending on its own: each account involved must be connected, and supplier payments also need the approval of an authorized user.

## Account connections

A connection links a Broco account to your platform. The account owner creates it by signing in to Broco and giving consent. Your server stores the connection identifier and sends it in later requests.

| Use case | Who connects | Field | Example |
| - | - | - | - |
| Broco Pay | Merchant | `merchant_connection` | `conn_mrc_4f7Kp2` |
| Cash checkout | Merchant | `merchant_connection` | `conn_mrc_4f7Kp2` |
| Supplier payments | Paying business | `payer_connection` | `conn_biz_2Pk7Lm` |
| Marketplace cash reconciliation | Wholesaler | `beneficiary_connection` | `conn_ben_7Lw2cR` |

Customers who pay in cash and recipients of deliveries do not connect an account.

<Steps>
  <Step title="Start the connection">
    The account owner selects **Connect Broco** in your platform. Your platform redirects them to Broco.
  </Step>

  <Step title="Sign in and consent">
    They sign in to Broco, review what your platform will be allowed to do, and approve.
  </Step>

  <Step title="Store the connection">
    Broco returns them to your platform. Your server receives and stores the connection identifier.
  </Step>
</Steps>

The owner can revoke a connection from Broco at any time. Requests that use a revoked connection fail with `connection_not_authorized`.

## Server and browser responsibilities

| Action | Where it happens |
| - | - |
| Create a payment or a collection | Your server |
| Choose the receiving account | Your server, from a stored connection |
| Authorize a Broco Pay payment | Broco page or Broco app |
| Approve a supplier payment | Broco, by an authorized user |
| Confirm that an order or invoice is paid | Your server, from an event or a status check |
| Show a confirmation screen | Browser, after your server confirms |

The browser never chooses the account that receives funds. A redirect back to your website does not prove that a payment succeeded.

## Idempotency

Every creation request carries an `Idempotency-Key`. If the same request is sent again with the same key, Broco returns the original object and does not create a second one.

```bash Request header theme={null}
Idempotency-Key: ORD-10482-attempt-1
```

See [Errors & retries](/developer/errors-and-retries) for retry rules.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.