:::endpoint POST /v1/me/broadcasting/auth

What the socket library calls when it subscribes to a private channel. Your
connection hands you a `socket_id`, you send it here with the channel you want,
and you get back the signature the socket needs.

Point your client's auth endpoint at this URL and send the token in the
`Authorization` header, exactly as on every other call.

## Two channels, and no others

An app may ask for these:

| Channel                             | What arrives                                                   |
| ----------------------------------- | -------------------------------------------------------------- |
| `private-App.Models.User.{your id}` | Your notifications, as they are raised                         |
| `private-mail-address.{mailbox id}` | `mail.received` when a message lands in a mailbox you can read |

Anything else is refused here. The channel definitions behind this endpoint were
written for the browser, where the address bar already says which propfirm
somebody is looking at, and a token has no address bar.

## What to use it for, and what not to

A socket is for the screen somebody is looking at right now: mail appearing in an
open list, a conversation growing while it is read.

It is not how an app finds out about mail when it is closed. Nothing arrives over
a socket that is not connected, and a mobile operating system will not keep one
alive in the background. Close it when the app goes to the background and rely on
push notifications there.

## Request

```bash
curl -X POST https://api.proppertrading.com/v1/me/broadcasting/auth \
  -H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f4a5b6c-7d8e-4f90-a1b2-c3d4e5f60718" \
  -d '{"channel_name": "private-mail-address.32", "socket_id": "123456.789012"}'
```

## Response

The shape the socket expects, which is the broadcaster's contract rather than
ours, so it is handed back as it comes:

```json
{ "auth": "qjumnez25xejvxzahi9f:94750334014f307fd797e0de0b466e4a08b1257c" }
```

## The event

`mail.received` on a mailbox channel carries a list row, never a body:

```json
{
    "message": {
        "id": 1552,
        "thread_id": 611,
        "address_id": 32,
        "folder": "inbox",
        "from_email": "jamie@example.com",
        "from_name": "Jamie Rivera",
        "subject": "Payout request",
        "preview": "Hi, I passed the evaluation last week",
        "has_attachments": false,
        "message_at": "2026-08-19T13:30:36.000000Z"
    },
    "unread_inbox": true
}
```

Enough to add a row and tick a badge. Reading it still means
[opening it](/docs/api/mail/message), which is where the body is sanitised and
where being allowed to read it is checked again.

Spam is broadcast too, with its folder attached. Silently withholding it would
make a false positive invisible instead of merely tucked away.

## Errors

| Status | Code                      | Meaning                                          |
| ------ | ------------------------- | ------------------------------------------------ |
| 400    | `missing_idempotency_key` | Every POST needs one                             |
| 403    | `channel_not_allowed`     | Not one of the two, or a mailbox you cannot read |
| 403    | `insufficient_scope`      | This device does not hold `me:read`              |
| 422    | `validation_failed`       | `channel_name` or `socket_id` missing            |