Guía para desarrolladores
Referencia de ámbitos
Los ámbitos de permiso detallados te permiten limitar a qué puede acceder una clave de API o un cliente OAuth dentro de un espacio de trabajo.
Resumen
Los ámbitos son cadenas separadas por espacios asociadas a una clave de API o a un cliente OAuth. Cuando llega una petición, la API valida los ámbitos del token frente a la operación solicitada. Sigue el mismo modelo que GitHub y Stripe: familiar, auditable y fácil de razonar.
Los ámbitos son opcionales. Si no se especifica ninguno, la credencial tiene acceso completo al espacio de trabajo (equivalente a un admin). Recomendamos asignar los ámbitos mínimos necesarios para cada integración.
Ámbitos
| Ámbito | Qué concede | Métodos | Endpoints |
|---|---|---|---|
polls:read | Leer encuestas, su contenido y metadatos. | GET | /polls, /polls/{id} |
polls:write | Crear, actualizar y eliminar encuestas. | POST, PATCH, DELETE | /polls, /polls/{id} |
results:read | Leer los resultados agregados por diapositiva y el registro de votantes. | GET | /polls/{id}/results, /polls/{id}/responses, /polls/{id}/votes |
responses:write | Enviar respuestas y votos a las encuestas. | POST | /polls/{id}/responses, /polls/{id}/votes |
sessions:write | Crear y controlar sesiones en vivo. | POST | /sessions, /sessions/{id}/control |
sessions:read | Leer el estado de la sesión en vivo (estado, diapositiva actual, número de participantes). | GET | /sessions/{id} |
media:write | Subir y servir medios (imágenes, YouTube) para usar en preguntas. | POST | /media |
export:read | Descargar los resultados como archivo CSV o informe PDF. | GET | /polls/{id}/export |
ai:write | Usa la IA para generar contenido de encuestas. | POST | /polls/{id}/branch |
Ámbitos en claves de API
Los ámbitos de las claves de API se aplican en cada petición. Una clave creada con un conjunto de ámbitos no vacío solo puede llamar a los endpoints cubiertos por ellos: una petición que necesite un ámbito que la clave no tiene devuelve 403 insufficient_scope. Una clave creada sin ámbitos tiene acceso completo al espacio de trabajo (ver Predeterminado más abajo). Asigna los ámbitos al crearla en el portal para desarrolladores.
Ámbitos en clientes OAuth
Los clientes OAuth aplican los ámbitos en el momento de emitir el token. Cuando llamas a POST /api/oauth/token con un parámetro scope, solo se conceden los ámbitos asignados al cliente al crearlo. Pedir un ámbito no asignado se descarta silenciosamente del token.
Si la petición de token no envía scope, el token hereda todos los ámbitos asignados al cliente (o acceso completo si el cliente no tiene ninguno).
Consulta la guía de OAuth 2.0 para un recorrido completo de configuración.
Predeterminado (sin ámbitos especificados)
Las credenciales sin ámbitos asociados tienen acceso completo al espacio de trabajo, equivalente a un admin. Úsalo para:
- Automatización personal en un espacio de trabajo propio
- Prototipos y desarrollo
Para integraciones en producción compartidas entre equipos o con terceros, especifica siempre los ámbitos mínimos necesarios.
¿Aún tienes preguntas?
Nuestro equipo estará encantado de ayudarte.