# Contexts

Every credential acts in exactly one context (a utility, its sandbox, an organization or a resident account); how to tell which, how to switch, and what happens to keys when access changes.


A context is where a request acts: a water utility's live account, that utility's sandbox, an organization, the platform or a resident's account. One person can hold several, but each credential acts in exactly one. The data a request reads and changes, and the permissions that apply to it, always belong to that context.

## Context fields

Session responses (`AuthSession`) and `GET $AUTH_API/me` describe each context with an `AuthContext` object:

| Field | Meaning |
| :--- | :--- |
| `id` | The context identifier, used to switch to it. |
| `type` | `platform`, `tenant`, `organization` or `consumer`. |
| `kind` | How the person reaches the context: `member`, `organization`, `agreement` or `support`. |
| `mode` | `live` or `sandbox`. A sandbox is a separate context with its own data. |
| `tenant_id`, `tenant_name` | The utility, when the context belongs to one. |
| `roles`, `scopes` | The roles and permissions the person holds there. |

`active_context` is the context of the current token, and `contexts` lists every context the person can switch to.

## API keys

An API key is pinned to the context it was created in. No header or parameter makes it act anywhere else: to work in both the sandbox and live, create an `sk_test_` key in the sandbox and an `sk_live_` key in the live account. A key created by a person stays tied to that person: if they are disabled, their membership of the utility ends, or they lose one of the scopes the key carries, the key is refused with `401`.

## Session and OAuth tokens

An access token acts in the context chosen at sign-in (the `context_id` sent when signing in or, without one, the person's preferred context). To move, ask for a new session:

```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": "en-US",
    "status": "active",
    "email_verified": true,
    "phone_verified": false,
    "created_at": "2026-10-02T09:15:00Z"
  },
  "active_context": {
    "id": "mbr_2mB5uL0rXy2SgA8oMd4WiQ9tEkF",
    "type": "tenant",
    "initials": "DU",
    "kind": "member",
    "mode": "sandbox",
    "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
    "tenant_name": "Demo utility",
    "roles": ["admin"],
    "scopes": ["business:customers:read", "developer:read", "developer:write"]
  },
  "contexts": []
}
```

✓ Checkpoint: `active_context.id` equals the `context_id` you asked for. Sending `refresh_token` ends the previous session, and the switch is written to the audit trail. A real response fills `contexts`; it is trimmed here.

An unknown or inactive context returns `403`. If the target utility requires a second factor on switch, the response is `401` with `step_up_required` until you resend the request with `step_up_code`, or `403` with `MFA_ENROLLMENT_REQUIRED` when the person has no authenticator set up. OAuth clients can also pass `context_id` on a `grant_type=refresh_token` request to `/oauth/token`.

## The X-Context-ID header

`X-Context-ID` applies only to requests made with the dashboard's session cookie: it picks the context for that one request without changing the session. If the context is not available to the session, the response is `403` with `code: "context_unavailable"`. Requests sent with `Authorization: Bearer` ignore it.

## From the command line

`gotactl contexts list` lists the contexts of the signed-in account, `gotactl contexts use <id>` moves the active OAuth session to another context (its `--web` flag falls back to browser PKCE when the server asks for interaction), and `gotactl whoami` shows the current identity, active context or the details of the key in use.

## Next steps

- [Pick the right credential](/docs/getting-started/authentication)
- [Create a key in the right context](/docs/getting-started/api-keys)
- [Work in the sandbox](/docs/getting-started/sandbox)

