Guia do desenvolvedor
Referência de escopos
Escopos de permissão detalhados permitem limitar o que uma chave de API ou cliente OAuth pode acessar dentro de um espaço de trabalho.
Visão geral
Escopos são cadeias separadas por espaço vinculadas a uma chave de API ou cliente OAuth. Quando chega uma requisição, a API valida os escopos do token contra a operação solicitada. É o mesmo modelo do GitHub e da Stripe: familiar, auditável e fácil de raciocinar.
Escopos são opcionais. Se nenhum for especificado, a credencial tem acesso total ao espaço de trabalho (equivalente a um admin). Recomendamos atribuir o mínimo de escopos necessário a cada integração.
Escopos
| Escopo | O que concede | Métodos | Endpoints |
|---|---|---|---|
polls:read | Ler enquetes, seu conteúdo e metadados. | GET | /polls, /polls/{id} |
polls:write | Criar, atualizar e excluir enquetes. | POST, PATCH, DELETE | /polls, /polls/{id} |
results:read | Ler os resultados agregados por slide e a lista de quem votou. | GET | /polls/{id}/results, /polls/{id}/responses, /polls/{id}/votes |
responses:write | Enviar respostas e votos às enquetes. | POST | /polls/{id}/responses, /polls/{id}/votes |
sessions:write | Criar e controlar sessões ao vivo. | POST | /sessions, /sessions/{id}/control |
sessions:read | Ler o estado da sessão ao vivo (status, slide atual, número de participantes). | GET | /sessions/{id} |
media:write | Enviar e servir mídia (imagens, YouTube) para usar nas perguntas. | POST | /media |
export:read | Baixar os resultados como arquivo CSV ou relatório PDF. | GET | /polls/{id}/export |
ai:write | Use a IA para gerar conteúdo de sondagens. | POST | /polls/{id}/branch |
Escopos em chaves de API
Os escopos das chaves de API são aplicados em toda requisição. Uma chave criada com um conjunto de escopos não vazio só pode chamar os endpoints cobertos por eles: uma requisição que exija um escopo ausente retorna 403 insufficient_scope. Uma chave criada sem escopos tem acesso total ao espaço de trabalho (veja Padrão abaixo). Defina os escopos ao criá-la no portal do desenvolvedor.
Escopos em clientes OAuth
Clientes OAuth aplicam escopos no momento da emissão do token. Ao chamar POST /api/oauth/token com o parâmetro scope, só são concedidos os escopos atribuídos ao cliente na criação. Pedir um escopo não atribuído faz com que ele seja descartado silenciosamente do token.
Se nenhum scope for enviado na requisição de token, o token herda todos os escopos atribuídos ao cliente (ou acesso total, se o cliente não tiver nenhum).
Veja o guia do OAuth 2.0 para o passo a passo completo de configuração.
Padrão (sem escopos especificados)
Credenciais sem escopos têm acesso total ao espaço de trabalho, equivalente a um admin. Use para:
- Automação pessoal em um espaço de trabalho que é seu
- Prototipagem e desenvolvimento
Para integrações em produção compartilhadas entre equipes ou com terceiros, especifique sempre os escopos mínimos necessários.
Ainda tem dúvidas?
Nossa equipe terá prazer em ajudar.