# Social accounts

> For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path).

Base URL `https://api.brixsignage.com`. Send `Authorization: Bearer $BRIX_API_KEY` unless an operation says Auth: none or Auth: no API key. The Permission line names what the key must hold. See [Authentication and scopes](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md).

- [GET /v1/social-accounts](#get-v1-social-accounts)
- [POST /v1/social-accounts](#post-v1-social-accounts)
- [PATCH /v1/social-accounts/{id}](#patch-v1-social-accounts-id)
- [DELETE /v1/social-accounts/{id}](#delete-v1-social-accounts-id)
- [GET /v1/social-accounts/preview-token](#get-v1-social-accounts-preview-token)

Every 4xx and 5xx response below returns this body:

| Field | Type | Description |
| --- | --- | --- |
| `error` | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
| `message` | string | Human-readable explanation. Safe to show an operator. |
| `requestId` | string | Present on 5xx: quote it to support. |

## GET /v1/social-accounts

List social accounts

List the social accounts connected to your workspace. Use the provider query parameter, for example provider=youtube, to filter by provider. Each result includes the display name and connection status for the account, but never the stored credentials.

**Notes.**
- Only accounts at locations the caller can see. Credentials are never returned.

Auth: Bearer token. Permission: `integration.view`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `provider` | query | string | no | Only accounts of this provider, e.g. `instagram`. |

```bash
curl "https://api.brixsignage.com/v1/social-accounts" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].id` | string |  |
| `data[].provider` | string | `instagram`, `facebook`, `youtube`, `google-calendar`, `google-sheets`, … |
| `data[].externalId` | string | The account's id at the provider. |
| `data[].displayName` | string |  |
| `data[].nodeId` | string \| null |  |
| `data[].expiresAt` | string \| null | When the provider's access expires, if known. |
| `data[].needsReconnectAt` | string \| null | Set when the provider refused the stored access: sign in again. |
| `data[].createdAt` | string | ISO-8601 timestamp (UTC). |
| `data[].updatedAt` | string | ISO-8601 timestamp (UTC). |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## POST /v1/social-accounts

Add social account

Create a social account connection by submitting its credentials directly. Credentials are encrypted before they are stored. For most providers, use the provider's OAuth start endpoint instead, since it handles sign-in and consent on your behalf.

Auth: Bearer token. Permission: `integration.create`.

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | string | yes |  |
| `externalId` | string | yes |  |
| `displayName` | string | yes |  |
| `creds` | object | yes | The provider credential (for example access and refresh tokens). Encrypted; never returned. |
| `nodeId` | string \| null | no |  |
| `expiresAt` | string \| null | no |  |

```bash
curl -X POST "https://api.brixsignage.com/v1/social-accounts" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success: An account of the same provider and external id that needed a new sign-in was reconnected instead: its id is returned.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |

Response 201: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `integration.create` at the location.

Response 422: `provider`, `externalId`, `displayName` or `creds` is missing, or a location outside this workspace.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## PATCH /v1/social-accounts/{id}

Update social account

Update a connected social account by its ID. You can change its display name or move it to a different location in your organization.

**Notes.**
- Answers `{ ok: true }`, not the account.

Auth: Bearer token. Permission: `integration.edit`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Social account id. |

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `displayName` | string | no |  |
| `nodeId` | string \| null | no | Move the account; you need `integration.edit` at the destination too. |
| `creds` | object | no | Replaces the stored credential and clears `needsReconnectAt`. |

```bash
curl -X PATCH "https://api.brixsignage.com/v1/social-accounts/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.ok` | true |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You cannot move the account to that location.

Response 404: No such account in this workspace.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## DELETE /v1/social-accounts/{id}

Remove social account

Delete a connected social account by its ID. This permanently removes the stored credentials and stops any apps that use the account from fetching new data.

**Notes.**
- Answers `{ ok: true }`.

Auth: Bearer token. Permission: `integration.delete`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Social account id. |

```bash
curl -X DELETE "https://api.brixsignage.com/v1/social-accounts/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.ok` | true |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404: No such account in this workspace.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## GET /v1/social-accounts/preview-token

Get social preview token

Get a short-lived token used to preview a live social app before it is published to a screen. Pass this token as the dt query parameter when calling social feed endpoints from a preview. The token is issued only for your own workspace and cannot be requested for another one.

Auth: Bearer token. Permission: `integration.view`.

```bash
curl "https://api.brixsignage.com/v1/social-accounts/preview-token" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.token` | string | A new short-lived token that lets an app preview read this workspace's social feeds (the `dt` parameter). Minted on each call. |
| `data.expiresIn` | integer | Seconds until it expires (1800). |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 5XX: Server error. The body carries a `requestId` to quote to support.
