API authentication

The Showly REST API accepts two credential types. Pick the 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 is scoped to the single workspace it was created in and carries the scopes you grant it at creation time. Treat it as a credential.

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:

• audit-log as you, the issuing user (good for accountability).
• are bound to one workspace; create one per workspace you automate against.
• are revoked and rotated from the same UI. For CI, give each pipeline its own PAT and rotate it on a schedule.

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. Note: POST /oauth/token returns the raw RFC 6749/8628 body ({ "access_token", "token_type": "Bearer", "scope" }) — it does not use the standard { ok, data } envelope, so don't branch on ok there. 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 PAT or an MCP token, not the bridge.

Choosing wisely