API authentication

The Showly REST API accepts three credential types, in increasing order of formality. Pick the lightest one that fits your use case. The base URL is https://api.showly.ai — there is no version prefix and no Api-Version header.

Personal access tokens (PATs)

For: ad-hoc scripts, personal automation.

Issue from Profile → API tokens → New token. A PAT inherits your roles across every workspace you belong to. That makes them easy but powerful — treat them as credentials.

GET /sites HTTP/1.1
Host: api.showly.ai
Authorization: Bearer sk_live_...

PATs use the sk_live_ prefix (or sk_test_ for the sandbox). They:

• carry your username in audit logs (good for accountability).
• get revoked when you leave a workspace (you lose access; the token survives but loses scope).
• are revoked and rotated from the same UI.

Service tokens

For: CI, deploy bots, integrations that don't belong to a person.

Issue from Workspace settings → API tokens. Service tokens are scoped to a single workspace and a single role. They survive their issuer's departure (which makes them durable for long-running automation but also means you must rotate them on a schedule).

Authorization: Bearer sk_live_...

Service tokens audit-log as service:<name> rather than a user. Pair every service token with a Notes entry describing what it's for, so a year from now someone can still answer "what does this do?"

MCP tokens (device flow)

For: agents and MCP clients (Claude Code, Codex) that act on a user's behalf.

Agent clients authenticate with an MCP token, obtained through the RFC 8628 device authorization flow. The token is minted bound to the authorizing user and carries the scopes they consent to. MCP tokens use the mcp_live_ prefix (or mcp_test_ for the sandbox).

Start the flow by requesting a device code:

POST /oauth/device
Content-Type: application/x-www-form-urlencoded

client_id=<your-app>
&scope=site:read preview:create

The user approves the request in the browser (the device flow lookup/authorize endpoints back the verification page). Meanwhile, poll the token endpoint with the device code until the user completes approval:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=<device-code>
&client_id=<your-app>

On success this mints an MCP token. Scopes use the canonical resource:verb vocabulary (for example site:read, preview:create); see Scopes and tokens for the full catalog so REST and MCP stay in sync.

There is no grant_type=refresh_token endpoint. To renew an MCP token, rotate it: POST /admin/mcp-tokens/:tokenId/rotate.

Session bridge (internal)

The Showly Web app calls the API on behalf of cookie-authenticated users via a _session bridge_: Web validates the cookie, then forwards the request with a special bridge header. This isn't documented as a public surface — it's a private contract between Web and API. If you're building an integration, use a service token or an MCP token, not the bridge.

Choosing wisely

Don't use PATs in CI; you'll forget to rotate them and they'll outlive you in the workspace.