> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Trabalhando com Organizações

> Como operar a API em nome de uma organização usando o header X-Organization-Id

# 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:

```bash theme={null}
curl https://portal.unicontrol.me/v1/states \
  -H "Authorization: Bearer pat_seu_token" \
  -H "X-Organization-Id: org_abc123"
```

<Info>
  Quando o header está presente, o Portal válida que você e membro da organização. Caso contrario, retorna `403 Forbidden`.
</Info>

## Descobrindo organizações

Liste as organizações do usuário autenticado:

```bash theme={null}
# Organizacoes que voce e dono
curl https://portal.unicontrol.me/v1/organizations/owned \
  -H "Authorization: Bearer pat_seu_token"
```

Resposta:

```json theme={null}
[
  { "id": "org_abc123", "name": "Casa de Praia" },
  { "id": "org_xyz789", "name": "Escritorio" }
]
```

## Papeis e permissões

Dentro de uma organização existem dois papeis:

| Papel      | Capacidades                               |
| ---------- | ----------------------------------------- |
| **admin**  | Acesso total a recursos da organização    |
| **member** | Acesso 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).

<Tip>
  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.
</Tip>

## Padrão recomendado

```python theme={null}
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()
```