Contextos
Cada credencial actua num único contexto (uma empresa, o seu sandbox, uma organização ou uma conta de morador); como saber qual é, como mudar de contexto e o que acontece às chaves quando o acesso muda.
Um contexto é o lugar onde um pedido actua: a conta de uma empresa de água em modo real, o sandbox dessa empresa, uma organização, a plataforma ou a conta de um morador. A mesma pessoa pode ter vários, mas cada credencial actua em exactamente um. Os dados que um pedido lê e altera, e as permissões que se aplicam, são sempre os desse contexto.
Os campos de um contexto#
As respostas de sessão (AuthSession) e GET $AUTH_API/me descrevem cada contexto com o objecto AuthContext:
| Campo | Significado |
|---|---|
id |
Identificador do contexto, usado para mudar de contexto. |
type |
platform, tenant, organization ou consumer. |
kind |
Como a pessoa chega ao contexto: member, organization, agreement ou support. |
mode |
live ou sandbox. O sandbox é um contexto à parte, com os seus próprios dados. |
tenant_id, tenant_name |
A empresa, quando o contexto é de uma empresa. |
roles, scopes |
Os papéis e as permissões que a pessoa tem nesse contexto. |
active_context indica o contexto do token actual e contexts lista todos aqueles para onde a pessoa pode mudar.
Chaves de API#
Uma chave de API fica presa ao contexto em que foi criada. Não há cabeçalho nem parâmetro que a faça actuar noutro: para trabalhar no sandbox e em modo real, crie uma chave sk_test_ no sandbox e outra sk_live_ na conta real. Quando a chave foi criada por uma pessoa, continua ligada a essa pessoa: se a pessoa for desactivada, se a sua participação na empresa terminar ou se perder uma das permissões que a chave tem, a chave passa a ser recusada com 401.
Tokens de sessão e OAuth#
Um token de acesso actua no contexto escolhido ao entrar (o context_id enviado no início de sessão ou, sem ele, o contexto preferido da pessoa). Para mudar, peça uma sessão nova:
curl -sS -X POST "$AUTH_API/switch" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"context_id":"mbr_2mB5uL0rXy2SgA8oMd4WiQ9tEkF","refresh_token":"'"$REFRESH_TOKEN"'"}'
{
"access_token": "eyJhbGciOiJFUzI1NiJ9.eyJzdWIiOiJ1c3JfMm1CNHRLOXFXeDFSZlo3bkxjM1ZoUDhzRGpFIn0.k3Vb7QxN2pR8sT1uW4yZ6aC9dF0gH5jL",
"token_type": "Bearer",
"expires_in": 900,
"refresh_token": "Zq8vN3kR7tW1yB5cF9hJ2mP6sU0xA4dG",
"user": {
"id": "usr_2mB4tK9qWx1RfZ7nLc3VhP8sDjE",
"full_name": "Helena Macuácua",
"locale": "pt-MZ",
"status": "active",
"email_verified": true,
"phone_verified": false,
"created_at": "2026-10-02T09:15:00Z"
},
"active_context": {
"id": "mbr_2mB5uL0rXy2SgA8oMd4WiQ9tEkF",
"type": "tenant",
"initials": "ED",
"kind": "member",
"mode": "sandbox",
"tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
"tenant_name": "Empresa de demonstração",
"roles": ["admin"],
"scopes": ["business:customers:read", "developer:read", "developer:write"]
},
"contexts": []
}
Um contexto desconhecido ou inactivo devolve 403. Se a empresa de destino exigir um segundo factor ao mudar, a resposta é 401 com step_up_required até reenviar o pedido com step_up_code, ou 403 com MFA_ENROLLMENT_REQUIRED se a pessoa não tiver autenticador configurado. Em clientes OAuth, o pedido grant_type=refresh_token a /oauth/token também aceita context_id.
O cabeçalho X-Context-ID#
O cabeçalho X-Context-ID só se aplica a pedidos feitos com o cookie de sessão do painel: escolhe o contexto desse pedido sem mudar a sessão. Se o contexto não estiver disponível para a sessão, a resposta é 403 com code: "context_unavailable". Pedidos com Authorization: Bearer não o usam.
Na linha de comandos#
gotactl contexts list lista os contextos da conta com sessão iniciada, gotactl contexts use <id> muda a sessão OAuth activa para outro contexto (a opção --web usa o browser com PKCE quando o servidor pede interacção) e gotactl whoami mostra a identidade, o contexto activo ou os dados da chave em uso.