PT EN

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:

bash
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"'"}'
json
{
  "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.

Próximos passos#