Authentication

ThreadzSocial uses Bearer authentication with API keys or Login with ThreadzSocial OAuth access tokens. Public read endpoints work without a credential; protected and write routes require a valid key or token.

Multi-tenant apps

To act on behalf of each seller’s own account, use OAuth (Login with ThreadzSocial). API keys always act as the developer who created the key.

API keys

Detail	Value
Format	`stz_{live\|sandbox}_{12hex}_{48hex}`
Lookup prefix	`stz_{env}_{12hex}` (unique)
Storage	SHA-256 of optional pepper + raw key. Full secret shown once at create.
Default scopes	`["read", "listings:write"]`
Create / revoke	Per app on /developers/apps
Legacy path	`/account/developer` redirects to apps

Live vs sandbox keys

Key environment	Prefix	Behavior
Sandbox	`stz_sandbox_…`	Writes and owner reads for sandbox listings only. Safe for integration tests. Never hits public Discover.
Live (production)	`stz_live_…`	Operates on the real marketplace. Requires go-live milestones / app production status. Treat as high sensitivity.

Choose sandbox while building

Create a sandbox key first. Complete milestones, then unlock production. See Go live and Sandbox.

Sending credentials

Pass the full secret in the Authorization header using the Bearer scheme:

Header

Authorization: Bearer stz_sandbox_a1b2c3d4e5f6_…

curl

curl -sS \
  -H "Authorization: Bearer stz_sandbox_YOUR_FULL_KEY" \
  https://www.threadzsocial.com/api/v1/me

Common headers

Header	When	Notes
`Authorization`	Protected & write routes	`Bearer <api_key>`
`Content-Type`	`POST` / `PATCH` JSON bodies	`application/json`
`Idempotency-Key`	Recommended on `POST /listings`	Maps to listing `external_id` (max 128 chars). Safe retries for the same seller + environment. See Listings.

When a key is required

Mode	When
None (anonymous)	Public GET health, listings (live feed), profiles
API key	`GET /me`, listing writes, sandbox inventory listing

Auth outcomes

Situation	HTTP	Code
No Authorization on public GET	200	—
Valid Bearer	200	—
Missing key on protected route	401	`unauthorized`
Invalid / revoked / expired key	401	`unauthorized`
Valid key, missing scope	403	`forbidden`
Key presented but server cannot validate	503	`service_unavailable`
Rate limit exceeded	429	`rate_limited`

Scopes

Keys carry a list of scopes. New keys default to read and listings:write. Scope * or admin (if ever issued) grants all permissions.

GET /me → requires read
POST / PATCH / DELETE listings → requires listings:write

Lifecycle best practices

Name keys by environment and purpose (e.g. “CI sandbox”).
One key per service; rotate by creating a new key then revoking the old.
Never commit keys. Use environment variables or a secret manager.
Revoke immediately if leaked from your app dashboard.

Login with ThreadzSocial (partners)

Building a product for many independent sellers? Prefer Login with ThreadzSocial (OAuth): each user authorizes only their own closet, then your app calls /api/v1/me and listings with their access token. API keys remain the right fit for single-seller scripts and your own automation.

Agree to the terms

API use is covered by the API Terms of Use and platform Terms of Service.