Authentication

Resolve credentials, establish sessions, and replay authorized requests deterministically.

SiteKit treats authentication as a pluggable adapter capability and runtime lifecycle. Auth is not just a strategy name; it is the part of the adapter that keeps a usable, authorized session alive.

Adapter And Connection

The adapter is shareable and holds no secrets. The connection is local, per-user or per-environment, and never published.

# adapter.yaml - publishable
auth:
  strategy: captured_headers
  requiredHeaders:
    - authorization
    - x-access-key
  probe:
    operation: users.current
    expect: nonEmpty

# connections/destination_portal-local.yaml - ignored by git
adapter: destination_portal@0.1.4
credentials:
  provider: 1password
  item: Destination Portal
session:
  cookieJar: ~/.sitekit/jars/destination_portal-local.json
onExpiry:
  notify:
    webhook: https://hooks.example.test/sitekit/session-expired

Generated clients take a connection, not a bare adapter. That keeps reusable adapter code separate from live credentials, session jars, and escalation rules.

Lifecycle

resolve credentials
  -> establish browser session
  -> capture cookies or headers
  -> probe
  -> refresh
  -> re-login
  -> escalate to a human

Adapters declare how to create and probe a session. The runtime owns when to refresh, when to retry, and when to stop rather than hammering a provider with a dead credential.

MVP Strategies

Username and Password

auth:
  strategy: browser_login
  loginUrl: https://app.example.test/login
  usernameSelector: input[name="email"]
  passwordSelector: input[name="password"]
  submitSelector: button[type="submit"]

The browser engine can fill common login forms, then fall back to manual login when MFA, SSO, or layout changes require a human.

Captured Headers

auth:
  strategy: captured_headers
  requiredHeaders:
    - authorization
    - x-access-key

The browser establishes a session. SiteKit captures the headers the frontend uses and replays them with direct HTTP.

auth:
  strategy: cookie_jar
  csrf:
    cookiePattern: csrf
    header: x-csrf-token

SiteKit exports HttpOnly cookies from Chrome through CDP, stores the live jar securely, and echoes CSRF cookies into headers when required.

Secret Providers

sitekit connection create destination_portal-local \
  --adapter destination_portal \
  --provider 1password \
  --item "Destination Portal"

sitekit connection create source_portal-cron \
  --adapter source_portal \
  --provider env \
  --prefix SITEKIT_SOURCE_PORTAL

Supported provider shape:

Environment variables for servers and cron.
1Password for local development and MCP users.
macOS Keychain as a local provider.
Cloud secret managers later.

Session Probes

Every adapter defines a cheap liveness probe:

probe:
  method: POST
  path: /graphql
  body:
    operationName: CurrentUser
    variables:
      workspaceId: ws_123

For GraphQL, HTTP 200 is not enough. The probe also checks for errors in the response body.

Refresh And Escalation

auth:
  lifecycle:
    probeBeforeRun: true
    refreshOn:
      status: [401, 403, 422]
      graphqlErrors:
        - ACCESS_DENIED
    relogin:
      mode: browser
      maxAttempts: 1

Connection policy says what happens when runtime auth cannot recover:

onExpiry:
  notify:
    webhook: https://hooks.example.test/sitekit/session-expired
  message: Session expired. Re-open browser login for this connection.

When a session expires mid-run, SiteKit should refresh once, preserve rotated cookies, and then fail loudly with a useful repair or login instruction.

For headless jobs, escalation must be machine-readable:

AuthExpiredError
  adapter: destination_portal@0.1.4
  connection: destination_portal-cron
  action: refresh_connection

The adapter cannot know who to wake up. The connection can.

On this page