Skip to content

Authentication ​

Every /api/v1 call is authenticated. There are two credentials (an API key for software, a session for the browser) and a required {brandId} path segment to target brand-scoped resources.

API keys ​

An API key belongs to your team, not to the person who made it, and acts only in that team: it keeps working when its maker leaves. Keys are made and revoked in the dashboard, on the Developer page, by any member of the team; a key can’t make or revoke another. The raw secret (sk_…) is returned once, at creation, and never again. Store it somewhere safe.

Send it as a bearer token on every request:

curl: a bearer token
curl "$API/brands/$BRAND/publications" -H "Authorization: Bearer sk_…"

TIP

The socialized.dev CLI stores the key for you (socialized.dev login) and attaches it to every request, so you don’t manage the header by hand. In CI, set SOCIALIZED_DEV_API_KEY instead of logging in.

Each key has an explicit scope:

AccessGrants
ReadRead brands, assets, publications, and webhooks
WriteRead + upload assets, edit webhooks, and publish videos
AdminWrite + create and rename brands

Reach is either all brands in the team (including ones added later) or a selected brand list. A key that names a brand outside its reach gets 403 BrandOutOfScopeError; a key missing the requested action gets 403 InsufficientScopeError. Webhook endpoints have a reach of the same shape: a key manages only endpoints whose every brand it reaches, and an endpoint for all brands only if it reaches all brands too (Webhooks).

Brands ​

A brand is a publishing identity inside your team: it owns the connections and the publications. Connections and publications are brand-scoped, while assets are team-scoped (reusable across any brand in the team).

List your brands to retrieve their IDs:

curl: list your brands
# List your brands and pick one (the id looks like brand_…)
curl -s "$API/brands" -H "Authorization: Bearer $SK"
export BRAND="brand_…"

Each row carries its connectedPlatforms so you can see what’s wired up without an extra call, and an archivedAt timestamp (null for a live brand). DELETE /brands/{brandId} archives a brand: its platform connections are disconnected, writes under it return 409 BrandArchivedError, and its publication history stays readable — posts already live on platforms are not touched. The last live brand in a team can’t be archived (409 LastBrandError). Once you have a brand ID, target brand-scoped resources under /brands/{brandId}:

curl: a brand’s publications
curl "$API/brands/$BRAND/publications" -H "Authorization: Bearer $SK"

Sessions (the dashboard) ​

The web app authenticates with a session cookie (email magic-link or Google), not an API key, but it talks to the same /api/v1. Anything you read here about the API is exactly what the dashboard does. You never handle the session yourself; it’s mentioned only so the two credentials aren’t a mystery.

Connections, API keys, billing and the profile avatar are session-only dashboard actions. Publishing, asset uploads, webhooks and brands accept API keys when the key grants that resource/action.

Errors ​

A missing or invalid credential is 401 UnauthorizedError. An authenticated caller with no team yet is 403 NoTeamError (the dashboard makes one at the first sign-in). Naming a {brandId} that isn’t one of your brands is 404 BrandNotFoundError. Naming a brand outside a key’s reach is 403 BrandOutOfScopeError; missing a grant is 403 InsufficientScopeError. See Errors & idempotency for the full vocabulary.

The API is the product; the dashboard is its best-known client.