Skip to content
Indigo HQ Docs

Identity & Access Management

This page covers how users and machines authenticate to HQ, how requests are authorized, and how Indigo controls its own administrative access.

Identity provider

HQ uses AWS Cognito as its identity platform (a dedicated user pool and identity pool). Sign-in is federated:

  • Users sign in through Google or Microsoft (OIDC). Microsoft sign-in covers work and school accounts (Entra ID) and personal Microsoft accounts. In production, a WorkOS-brokered Microsoft sign-in path is also configured but is not yet used by the sign-in buttons.
  • GitHub is not a sign-in provider.
  • Native self-registration is blocked. The pool setting allowAdminCreateUserOnly is false, and a pre-sign-up check refuses every native SignUp request while allowing federated sign-ins and accounts that HQ’s own services create (machine, agent, and test identities).
  • The identity pool does not permit unauthenticated identities and enforces server-side token checks.

Because Google or Microsoft is the front door, customers inherit and control their own IdP-level posture — including enforced MFA, conditional access, and deprovisioning — for their HQ users.

Authentication flows

  • The desktop app and CLI authenticate with OAuth 2.0 Authorization Code flow with PKCE (S256) against the Cognito Hosted UI, federated to Google or Microsoft. The flow uses a loopback redirect, validates an anti-CSRF state parameter, is single-use, and times out quickly if not completed.
  • Token refresh uses Cognito’s refresh-token grant.
  • The API authorizes requests using the issued JSON Web Tokens (below).

Tokens and session management

  • Token types and lifetimes: short-lived access and ID tokens (1 hour). Refresh tokens last 90 days for the main client used by the desktop app, CLI, and web console; 30 days for some other web clients; and 1 day for most machine clients. Hosted agent machines (Outposts) are the exception: each signs in as its own Cognito user with a permanent machine password, through a dedicated client that issues 24-hour access and ID tokens and 3,650-day (10-year) refresh tokens.
  • Client storage: on desktop, the primary token store is ~/.hq/cognito-tokens.json with owner-only permissions (0600), shared with the hq CLI. Signed macOS builds also mirror the tokens to the macOS Keychain; when the file and the Keychain differ, the file wins, and the Keychain copy is used only if the file cannot be read.
  • Revocation: CLI sign-out revokes the refresh token with Cognito; account deletion signs the user out of all sessions. Membership/authorization changes take effect on the next request because access credentials are recomputed per request and never cached (see Tenant Isolation).

Authorization model

Every API route is protected by an API Gateway JWT authorizer that validates the token’s issuer and audience before any handler runs. Within a request, authorization is resolved as follows:

  1. The verified token identifies the caller.
  2. The caller maps to an organization membership with a role — owner, admin, member, or guest — and a set of permitted path prefixes (including explicit grants and deny carve-outs).
  3. These permissions are compiled into a least-privilege, time-boxed AWS STS session scoped to a single tenant’s storage and key. The platform then enforces the boundary at the infrastructure layer.

This means an authorization decision is expressed not only in application logic but as an AWS credential that is incapable of exceeding its scope.

Machine and agent identity

HQ runs autonomous agents, which require their own identities:

  • Scoped agent identities: machine principals are issued as dedicated Cognito identities carrying a company claim, so their access is constrained to a single organization, enforced from the verified claim at request time.
  • API keys: issued as high-entropy bearer keys, shown to the operator once, and stored only as a SHA-256 hash — the plaintext is not retained server-side.
  • Local/CLI agents authenticate using the signed-in user’s own Cognito tokens; they do not hold a separate long-lived secret.
  • Hosted agent machines (Outposts) each have their own Cognito user with a permanent machine password and a 10-year refresh token (see Tokens and session management). Their delegated claims name the owning person for authorization.

Owner delegation

An agent can act on behalf of one of its owners — the person who created it, plus anyone they explicitly invite as an owner. When a request is confidently attributed to an active owner (for example, a recognized owner messaging the agent in Slack), the agent’s acting context is derived from that owner’s own permissions, expressed as a strict-subset, time-boxed child STS session that can never exceed the owner’s grants. Otherwise the agent falls back to its own default identity. Delegation follows the same least-privilege model as the rest of the platform, plus these guardrails:

  • Only the requester-owner’s permissions. The agent borrows exactly one owner’s access, never a union of several owners, and never more than that owner can already reach.
  • Identity is never guessed. If the requester can’t be confidently resolved to an owner, the agent acts as itself rather than assuming. Cross-workspace Slack identities are matched only via an explicit, self-serve account link.
  • Membership and status are re-checked per request. Revoking an owner (or their underlying access) takes effect on the next request; the credentials are recomputed each time and never cached.
  • Per-tenant control. Delegation is enabled by default and can be disabled per company; a global switch remains as a platform-level control.

Owner grants and delegation decisions are recorded in the audit trail.

Administrative (Indigo staff) access

  • Staff administrative capability is restricted to vetted Indigo personnel and gated on a verified internal identity.
  • Privileged actions — including any support impersonation — are recorded in the audit trail (which principal acted, on whose behalf, when).
  • Indigo follows least-privilege for internal access and is formalizing periodic access reviews as part of the SOC 2 program (see Compliance Roadmap).

Multi-factor authentication

  • MFA is enforced at the identity provider (Google or Microsoft). Customers control MFA strength and enforcement for their own users through their identity-provider policies.
  • Native, platform-level MFA inside Cognito is not yet implemented and is on the roadmap as a defense-in-depth addition independent of the upstream IdP.

Customer-facing access-management capabilities

Customers can:

  • Invite and remove members, and assign roles (owner, admin, member, guest).
  • Grant and revoke path-scoped access to specific resources.
  • Share resources externally via single-use, time-limited capability links (never by widening base access).
  • Rely on their identity provider to deprovision a departing employee’s access centrally.

Honest limitations

  • No native (in-platform) MFA yet; MFA is currently inherited from the customer’s identity provider.
  • Refresh tokens are long-lived (90 days for the main desktop, CLI, and web console client; 10 years for hosted agent machine identities) and not rotated on use.
  • Hosted agent machine identities authenticate with a permanent machine password.
  • The desktop and CLI token file relies on filesystem permissions rather than encryption.
  • The main user-pool client also enables Cognito password (USER_PASSWORD_AUTH) and choice-based (USER_AUTH, including email one-time code) flows beyond what federated sign-in requires; tightening this is on the roadmap.

Each of these is tracked in the Compliance Roadmap.