Appearance
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:
| Access | Grants |
|---|---|
| Read | Read brands, assets, publications, and webhooks |
| Write | Read + upload assets, edit webhooks, and publish videos |
| Admin | Write + 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.