Authentication
Every request to https://viraloop.io/api/v1 is authenticated with an API key. Keys are created in the dashboard at https://viraloop.io/settings/developers and look like vl_live_....
Sending the key
Two headers are accepted; use whichever fits your HTTP client:
bash
curl -s https://viraloop.io/api/v1/me \
-H "Authorization: Bearer $VIRALOOP_API_KEY"
bash
curl -s https://viraloop.io/api/v1/me \
-H "X-API-Key: $VIRALOOP_API_KEY"Keys are accepted in headers only. Never put a key in a URL or query string; URLs end up in logs.
A missing or invalid key returns 401 with error type unauthorized.
Scopes
Each key carries a set of scopes chosen at creation. Calling an endpoint the key is not scoped for returns 403 with error type forbidden_scope.
credits:read: read the credit balance and ledger (GET /credits)workspaces:read: list and read workspaces (GET /workspaces, GET /workspaces/{id})workspaces:write: create workspaces (POST /workspaces)accounts:read: list connected social accounts (GET /accounts)generations:read: list and read content suggestions (GET /generations, GET /generations/{id})generations:write: generate content suggestions (POST /generations)posts:read: list and read posts and the calendar (GET /posts, GET /posts/{id}, GET /calendar)posts:write: create and cancel posts (POST /posts, DELETE /posts/{id})
GET /me works with any valid key regardless of scopes; use it to check which scopes a key has (data.auth.scopes).
Managing keys
Everything happens at https://viraloop.io/settings/developers:
- Create a key with a name and the scopes it needs
- The full key is shown once, at creation; only a prefix (like
vl_live_a1b2c3d4) is visible afterwards - Revoke a key at any time; revoked keys stop working immediately
Security notes
- Store keys in environment variables or a secret manager, never in source control
- Give each integration its own key with the minimum scopes it needs, so one leak has a small blast radius and revocation does not break everything else
- If a key leaks, revoke it in the dashboard and create a new one
- Keys act on behalf of your team; treat them like passwords