Organizações
Um usuário do Portal pode pertencer a varias organizações (além do espaco pessoal). Sua integração precisa dizer ao Portal qual organização está operando — caso contrario, age sobre o espaco pessoal do dono do token.O header X-Organization-Id
Inclua o ID da organização no header X-Organization-Id para que a requisição seja executada no contexto dela:
Quando o header está presente, o Portal válida que você e membro da organização. Caso contrario, retorna
403 Forbidden.Descobrindo organizações
Liste as organizações do usuário autenticado:Papeis e permissões
Dentro de uma organização existem dois papeis:
Para membros, o Portal aplica as permissões do recurso:
can_view,can_create,can_edit,can_delete,can_execute
automations, dashboards, scripts, config_entries, tags, edges, mais entidades/dispositivos compartilhados individualmente.
Sua integração pode receber 403 em endpoints específicos mesmo com um token válido — isso significa que o usuário não tem permissão naquela organização para aquele recurso. Trate como erro recuperável e mostre uma mensagem clara ao usuário final.
Como saber em qual contexto a chamada esta?
Ao chamarGET /v1/states sem o header, você le entidades do espaco pessoal do dono do token. Ao chamar com o header, le entidades da organização indicada (respeitando as permissões do papel).