Skip to main content

​
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: 
curl https://portal.unicontrol.me/v1/states \
  -H "Authorization: Bearer pat_seu_token" \
  -H "X-Organization-Id: org_abc123"
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: 
# Organizacoes que voce e dono
curl https://portal.unicontrol.me/v1/organizations/owned \
  -H "Authorization: Bearer pat_seu_token"
Resposta: 
[
  { "id": "org_abc123", "name": "Casa de Praia" },
  { "id": "org_xyz789", "name": "Escritorio" }
]

​
Papeis e permissões

Dentro de uma organização existem dois papeis:
PapelCapacidades
adminAcesso total a recursos da organização
memberAcesso filtrado por permissões granulares
Para membros, o Portal aplica as permissões do recurso:
  • can_view, can_create, can_edit, can_delete, can_execute
Tipos de recurso: 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 chamar GET /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).
Em integrações multi-tenant (varios clientes), peca ao usuário para escolher a organização no setup e armazene esse ID junto com o token. Não tente adivinhar.

​
Padrão recomendado

import os
import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['PORTAL_TOKEN']}"

org_id = os.environ.get("PORTAL_ORG_ID")
if org_id:
    session.headers["X-Organization-Id"] = org_id

# Agora toda chamada feita por `session` ja vai no contexto da org
states = session.get("https://portal.unicontrol.me/v1/states").json()