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

# Partner integrations

> Trade on behalf of a trader, at one firm, with a key the trader controls.

A **partner integration** is a third-party application — a trade copier, a
journal, an analytics tool — that acts on behalf of an individual trader
against the Trade API.

<Note>
  This is a supported, server-to-server integration path. It is separate from
  the [organization API key](/authentication) flow, which is for prop firms
  operating their own accounts from their own backend.
</Note>

## How it differs from an organization key

|                          | Organization key                                          | Partner integration                                  |
| ------------------------ | --------------------------------------------------------- | ---------------------------------------------------- |
| Who holds the credential | The prop firm                                             | The trader                                           |
| What it reaches          | The firm's whole tenant — accounts, plans, rules, billing | One trader's accounts, at one firm                   |
| Service                  | Platform API                                              | Trade API                                            |
| Credential               | `hp_live_...` org key                                     | Partner app credentials + the trader's `hpk_...` key |
| Who can revoke           | Firm admin                                                | The trader, at any time                              |

If you are a prop firm provisioning and managing accounts, you want the
Platform API and an org key — start at the [Quickstart](/quickstart). If you
are building a tool a trader connects their own account to, read on.

## Prerequisites

Partner applications are issued credentials by Hyperprop — an `app_id` and an
`app_secret`. These are not self-service: contact Hyperprop to have your
application reviewed and registered.

<Warning>
  Your `app_secret` is a server-side credential. Never ship it in a browser
  bundle, mobile binary, or anything else a trader can read.
</Warning>

## The flow

<Steps>
  <Step title="The trader generates a key">
    In the Hyperprop app, the trader creates an API key for your integration.
    The key looks like `hpk_...` and is theirs — they can list or revoke it at
    any time. Keys remain retrievable, so a trader can come back and copy the
    same key again rather than rotating it every time they reconnect.
  </Step>

  <Step title="The trader gives you the key and picks a firm">
    Your app collects the key and the firm they want to connect. A trader may
    hold accounts at several firms; each connection is scoped to exactly one.
  </Step>

  <Step title="You exchange all of it for a session token">
    Call `POST /trade/partner/session` with your app credentials, the trader's
    key, and the firm. You get back a short-lived bearer token.
  </Step>

  <Step title="You use that token as a normal Trade API bearer token">
    Orders, positions, brackets, WebSocket streaming — the whole Trade API,
    limited to the accounts the session returned.
  </Step>
</Steps>

### Exchanging credentials for a session

```bash theme={null}
curl -X POST "https://api.hyperprop.com/trade/partner/session" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "your-app-uuid",
    "app_secret": "your-app-secret",
    "api_key": "hpk_the_traders_key",
    "firm": "example-firm"
  }'
```

`firm` accepts an organization id, slug, or name.

```json theme={null}
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900,
  "organization_id": "3f2b7c9e-...",
  "organization_name": "Example Firm",
  "organization_slug": "example-firm",
  "account_ids": ["7c9e6679-...", "550e8400-..."]
}
```

Then call the Trade API with it:

```bash theme={null}
curl "https://api.hyperprop.com/trade/accounts" \
  -H "Authorization: Bearer eyJhbGciOi..."
```

## Firm scoping is absolute

The session token acknowledges **only** the trader's accounts at the firm you
named. Accounts the same trader holds at other firms are invisible to that
session — for reads, for writes, and for WebSocket events alike. They are not
filtered out of the UI; they are not addressable.

To act at a second firm, run the exchange again with the same trader key and a
different `firm`, and keep the two tokens separate.

## Token lifetime

Sessions are short-lived — treat `expires_in` (seconds) as authoritative
rather than hardcoding a number. There is no refresh token: when a session
expires, repeat the exchange with the stored trader key. Store the trader's
`hpk_...` key, not the session token.

## Revocation

A trader can revoke their key at any time from the Hyperprop app.

* New session exchanges with a revoked key fail immediately.
* Sessions already minted from it keep working until the token expires.

Revocation is permanent — a revoked key is never reinstated, and the trader
generates a new one to reconnect. Handle a `401` on the exchange as
"disconnected, ask the trader to reconnect", not as a retryable error.

<Note>
  Partner sessions cannot mint keys. Key creation requires the trader's own
  Hyperprop session, which keeps your integration out of the business of
  issuing credentials on a trader's behalf.
</Note>

## Rate limits and errors

The Trade API applies per-account rate limits; a partner session is subject to
the same buckets as the trader. Errors use the standard envelope with a
machine-readable `code` — switch on `code`, never on message text. The full
list is in the Trade API reference tab.

| Situation                                      | What you get |
| ---------------------------------------------- | ------------ |
| Bad app credentials, bad or revoked trader key | `401`        |
| Valid key, but no access to that firm          | `403`        |
| Too many exchange attempts                     | `429`        |

## Browser access

Run the session exchange from your **backend**. Trade API browser calls are
restricted to approved origins — that restriction applies to browsers only and
never to server-to-server calls, which send no `Origin` header. If your
product needs a browser to talk to the Trade API directly, contact us to get
your origin approved; it is a configuration change on our side.


## Related topics

- [Authentication](/authentication.md)
- [Generate a trader API key for third-party access](/trade-api/account/generate-a-trader-api-key-for-third-party-access.md)
- [Introduction](/introduction.md)
- [Changelog](/changelog.md)
- [Create a firm-scoped partner session](/trade-api/account/create-a-firm-scoped-partner-session.md)