API autenticación

El Showly REST API acepta dos tipos de credenciales. Elija el que se ajuste a su caso de uso. La URL base es https://api.showly.ai; no hay prefijo de versión ni encabezado Api-Version.

Tokens de acceso personal (PAT)

Para: scripts ad-hoc, automatización personal.

Emisión desde Perfil → API tokens → Nuevo token. Una PAT tiene como alcance el espacio de trabajo único en el que se creó y tiene los alcances que usted le otorga en el momento de su creación. Trátelo como una credencial.

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

Los PAT utilizan el prefijo sk_live_ (o sk_test_ para el entorno limitado). Ellos:

• registro de auditoría como usted, el usuario emisor (bueno para la responsabilidad).
• están vinculados a un espacio de trabajo; cree uno por espacio de trabajo en el que automatice.
• se revocan y rotan desde la misma interfaz de usuario. Para CI, asigne a cada canalización su propio PAT y rótelo según un cronograma.

MCP tokens (flujo de dispositivo)

Para: agentes y MCP clientes (Claude Code, Codex) que actúan en nombre de un usuario.

Los clientes agentes se autentican con un token MCP, obtenido a través del flujo de autorización de dispositivo RFC 8628. El token se acuña vinculado al usuario que autoriza y tiene los alcances que éste acepta. Los tokens MCP usan el prefijo mcp_live_ (o mcp_test_ para la zona de pruebas).

Inicie el flujo solicitando un código de dispositivo:

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

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

El usuario aprueba la solicitud en el navegador (los puntos finales de búsqueda/autorización de flujo del dispositivo regresan a la página de verificación). Mientras tanto, sondee el punto final del token con el código del dispositivo hasta que el usuario complete la aprobación:

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>

Si tiene éxito, esto genera una ficha MCP. Nota: POST /oauth/token devuelve el cuerpo RFC 6749/8628 sin formato ({ "access_token", "token_type": "Bearer", "scope" }); no utiliza el sobre estándar { ok, data }, así que no se ramifique en ok allí. Los ámbitos utilizan el vocabulario canónico resource:verb (por ejemplo site:read, preview:create); consulte Alcances y tokens para ver el catálogo completo, de modo que REST y MCP permanezcan sincronizados.

No hay ningún punto final grant_type=refresh_token. Para renovar una ficha MCP, gírela: POST /admin/mcp-tokens/:tokenId/rotate.

Elegir sabiamente