# 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": []
}
```

✓ Checkpoint: `active_context.id` é o `context_id` pedido. Ao enviar `refresh_token`, a sessão anterior é terminada; a mudança fica no registo de auditoria. A lista `contexts` vem preenchida na resposta real e foi encurtada aqui.

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

- [Escolher a credencial certa](/docs/getting-started/authentication)
- [Criar uma chave no contexto certo](/docs/getting-started/api-keys)
- [Trabalhar no sandbox](/docs/getting-started/sandbox)

