Social accounts API

Social accounts endpoints in the Brix REST API: 5 operations (GET, POST, PATCH, DELETE). Each lists its path, auth, required permission and a curl example.

View as Markdown

Base URL https://api.brixsignage.com. Send Authorization: Bearer $BRIX_API_KEY unless an operation says No auth. The permission chip names what the key must hold. See Authentication and scopes, Errors and rate limits and Pagination.

GET /v1/social-accounts
POST /v1/social-accounts
PATCH /v1/social-accounts/{id}
DELETE /v1/social-accounts/{id}
GET /v1/social-accounts/preview-token

GET/v1/social-accounts

Bearer token integration.view

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.

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

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.

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.

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

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.

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

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.

POST/v1/social-accounts

Bearer token integration.create

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.

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

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.

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.

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

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.

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

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.

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

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.

PATCH/v1/social-accounts/{id}

Bearer token integration.edit

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.

Parameter	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`.

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.

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.

Response 403 You cannot move the account to that location.

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.

Response 404 No such account in this workspace.

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.

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

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.

DELETE/v1/social-accounts/{id}

Bearer token integration.delete

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 }.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Social account id.

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.

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.

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

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.

Response 404 No such account in this workspace.

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.

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

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/preview-token

Bearer token integration.view

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.

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.

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.

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

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.

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

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

POST/v1/social-accounts

PATCH/v1/social-accounts/{id}

DELETE/v1/social-accounts/{id}

GET/v1/social-accounts/preview-token

Connect With Us

Message Received!