Escopos

Formato

Um escopo tem o formato grupo:read ou grupo:write, por exemplo tickets:read. O write inclui o read do mesmo grupo: ao criar ou editar uma chave marcando só o :write de um grupo, ela fica gravada — e aparece na tela — também com o :read desse grupo.

Os grupos reports, agents, email-boxes e ai-providers são somente leitura: só existem como :read.

expand e filtros por outro recurso

Pedir dados de outro recurso com expand, ou filtrar por outro recurso, exige também o escopo de leitura do recurso de destino. Sem ele, a resposta é 403 insufficient_scope.

Quando falta escopo

O 403 insufficient_scope traz o campo requiredScope no corpo e o cabeçalho WWW-Authenticate: Bearer error="insufficient_scope" (com o escopo exigido em scope). Edite a chave e adicione esse escopo, ou crie uma chave nova com ele. Veja Editar os escopos.

Se a empresa está com a API desabilitada, o erro é outro: scope_requires_public_api. Veja a Concessão de escopos.

Qual escopo cada operação exige

Escopo	Operações
reports:read	GET /v1/reports/{id} — Consulta um relatório personalizado e as colunas do resultado GET /v1/reports/{id}/count — Conta as linhas de um relatório personalizado GET /v1/reports/{id}/execute — Executa um relatório personalizado
settings:read	GET /v1/tags — Lista as tags da empresa da chave GET /v1/tags/{id} — Busca uma tag pelo id
settings:write	POST /v1/tags — Cria uma tag PATCH /v1/tags/{id} — Edita uma tag (merge patch) DELETE /v1/tags/{id} — Remove uma tag
tickets:read	GET /v1/tickets — Lista os tickets da empresa da chave GET /v1/tickets/{id} — Busca um ticket pelo id GET /v1/tickets/{id}/print — Imprime o relatório de atendimento GET /v1/tickets/{ticketId}/activities — Lista o histórico de um ticket GET /v1/tickets/{ticketId}/alerts — Lista os alertas de RMM vinculados a um ticket GET /v1/tickets/{ticketId}/appointments — Lista os apontamentos de um ticket GET /v1/tickets/{ticketId}/appointments/{appointmentId} — Busca um apontamento do ticket pelo id GET /v1/tickets/{ticketId}/appointments/summary — Soma as horas apontadas no ticket GET /v1/tickets/{ticketId}/attachments — Lista os anexos de um ticket GET /v1/tickets/{ticketId}/attachments/{attachmentId} — Busca um anexo do ticket pelo id GET /v1/tickets/{ticketId}/attachments/{attachmentId}/content — Baixa o conteúdo de um anexo GET /v1/tickets/{ticketId}/billable-items — Lista os itens faturáveis de um ticket GET /v1/tickets/{ticketId}/billable-items/{itemId} — Obtém um item faturável do ticket GET /v1/tickets/{ticketId}/chat-sessions — Lista as conversas do MSP Talks vinculadas a um ticket GET /v1/tickets/{ticketId}/chat-sessions/{linkId} — Lê uma conversa vinculada ao ticket GET /v1/tickets/{ticketId}/followers — Lista os seguidores de um ticket GET /v1/tickets/{ticketId}/message-templates/{templateId} — Aplica um modelo de mensagem a este ticket GET /v1/tickets/{ticketId}/notes — Lista as notas de um ticket GET /v1/tickets/{ticketId}/notes/{noteId} — Busca uma nota do ticket pelo id GET /v1/tickets/{ticketId}/tasks — Lista as tarefas de um ticket GET /v1/tickets/{ticketId}/tasks/{taskId} — Busca uma tarefa do ticket pelo id GET /v1/tickets/count — Conta os tickets da empresa da chave
tickets:write	POST /v1/tickets — Abre um ticket PATCH /v1/tickets/{id} — Altera um ticket DELETE /v1/tickets/{id} — Exclui um ticket POST /v1/tickets/{id}/complete — Conclui o ticket POST /v1/tickets/{id}/end-appointment — Encerra o atendimento sem preencher POST /v1/tickets/{id}/merge — Mescla tickets POST /v1/tickets/{id}/pause — Encerra o atendimento com o apontamento POST /v1/tickets/{id}/reopen — Reabre o ticket POST /v1/tickets/{id}/sla-pause — Pausa o SLA do ticket POST /v1/tickets/{id}/sla-resume — Retoma o SLA do ticket POST /v1/tickets/{id}/stage — Move o ticket de etapa POST /v1/tickets/{id}/start — Inicia o atendimento POST /v1/tickets/{id}/workflow — Troca ou desvincula o fluxo POST /v1/tickets/{ticketId}/appointments — Registra um apontamento no ticket PATCH /v1/tickets/{ticketId}/appointments/{appointmentId} — Altera um apontamento do ticket DELETE /v1/tickets/{ticketId}/appointments/{appointmentId} — Exclui um apontamento do ticket POST /v1/tickets/{ticketId}/attachments — Envia um anexo para o ticket DELETE /v1/tickets/{ticketId}/attachments/{attachmentId} — Exclui um anexo do ticket POST /v1/tickets/{ticketId}/billable-items — Lança um produto/serviço no ticket PATCH /v1/tickets/{ticketId}/billable-items/{itemId} — Edita um item faturável do ticket DELETE /v1/tickets/{ticketId}/billable-items/{itemId} — Exclui um item faturável do ticket POST /v1/tickets/{ticketId}/chat-conversations — Inicia uma conversa no MSP Talks a partir do ticket POST /v1/tickets/{ticketId}/chat-sessions — Vincula uma conversa existente do MSP Talks ao ticket PATCH /v1/tickets/{ticketId}/chat-sessions/{linkId} — Torna esta a conversa principal do ticket DELETE /v1/tickets/{ticketId}/chat-sessions/{linkId} — Desvincula a conversa do ticket POST /v1/tickets/{ticketId}/chat-sessions/{linkId}/notes — Escreve uma anotação interna na conversa do MSP Talks POST /v1/tickets/{ticketId}/followers — Adiciona um seguidor ao ticket DELETE /v1/tickets/{ticketId}/followers/{agentId} — Remove um seguidor do ticket POST /v1/tickets/{ticketId}/notes — Registra uma nota no ticket PATCH /v1/tickets/{ticketId}/notes/{noteId} — Altera o texto ou a visibilidade de uma nota DELETE /v1/tickets/{ticketId}/notes/{noteId} — Exclui uma nota do ticket POST /v1/tickets/{ticketId}/notes/forward — Encaminha o ticket para destinatários livres POST /v1/tickets/{ticketId}/notes/reply — Responde ao contato do ticket POST /v1/tickets/{ticketId}/tasks — Cria uma tarefa no ticket PATCH /v1/tickets/{ticketId}/tasks/{taskId} — Altera uma tarefa do ticket DELETE /v1/tickets/{ticketId}/tasks/{taskId} — Exclui uma tarefa do ticket POST /v1/tickets/{ticketId}/tasks/{taskId}/move — Reordena uma tarefa do ticket POST /v1/tickets/{ticketId}/tasks/from-template — Aplica um modelo de tarefas ao ticket