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