Secrets and auth

Credentials are declared once and referenced by name. User-defined secrets flow through context.secrets. Vendor integrations (AI, Resend, Firecrawl, Parallel) resolve their API keys internally: you do not read those keys from context.secrets in @ts blocks.

secret

Group related environment variable names (not values) in a top-level block. Values are set with swirls env set or the project vault.

secret api_k {
  label: "Third-party API"
  vars: [API_KEY, API_SECRET]
}

Node-level secrets:

On root { } or node name { }, list which vars from which blocks this node may access:

graph example {
  label: "Example"
  root {
    type: code
    label: "Entry"
    secrets: {
      api_k: [API_KEY]
    }
    code: @ts {
      const key = context.secrets.api_k.API_KEY
      return { hasKey: Boolean(key) }
    }
  }
}

Access pattern: context.secrets.<blockName>.<VAR>. See Context.

auth

Configure reusable authentication for HTTP nodes only. Reference a secret block via secrets:; field identifiers (client_id, token, key, etc.) must match names listed in that block’s vars.

OAuth (client credentials) example:

secret gh {
  label: "OAuth client"
  vars: [CLIENT_ID, CLIENT_SECRET]
}

auth oauth_ex {
  label: "Example OAuth"
  type: oauth
  secrets: gh
  grant_type: client_credentials
  client_id: CLIENT_ID
  client_secret: CLIENT_SECRET
  token_url: "https://example.com/token"
}

API key in a header:

secret api_k {
  vars: [API_KEY]
}

auth api_key_ex {
  type: api_key
  secrets: api_k
  key: API_KEY
  header: "X-Api-Key"
}

Basic and bearer:

secret basic_s {
  vars: [USER, PASS]
}

secret tok {
  vars: [BEARER]
}

auth basic_ex {
  type: basic
  secrets: basic_s
  username: USER
  password: PASS
}

auth bearer_ex {
  type: bearer
  secrets: tok
  token: BEARER
}

HTTP auth:

Only type: http nodes may set auth: <auth_block_name>. The runtime applies the configured auth to the request.

node call_api {
  type: http
  label: "Authenticated GET"
  auth: bearer_ex
  url: @ts { return "https://api.example.com/v1/profile" }
}

Do not duplicate auth in headers with hyphenated keys like Authorization built manually if you can use auth: instead. Avoid hyphenated keys in literal headers objects: they break the parser (see Syntax).

Inferred vendor keys

These are resolved by the runtime for the corresponding node types; they are not exposed on context.secrets for user code:

Set them with swirls env set or the dashboard.

Further reading

• Context: context.secrets typing
• Node types: http node fields