Auth blocks

What it is. A reusable description of how to authenticate with an external API using credentials you hold: where the token endpoint is, which header carries the key, which secret vars to read.

Use it when an HTTP node calls an API that needs OAuth2 client credentials, an API key header, basic auth, or a bearer token, or when you want to gate a public form with basic auth.

Works with secret blocks (an auth block reads its credential values from one) and type: http nodes. For Swirls-brokered OAuth apps (Slack, Linear, ...), use a connection instead.

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).

Further reading

• Connections: brokered OAuth with no credentials in the file
• Node types: http node fields