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

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#