Credential profiles

What it is. A credential profile: a reusable description of how to apply credentials you hold. The file declares the shape (token URL, header name, which secret vars to read); the vault holds the values. In the DSL the keyword is auth.

Use it when an HTTP node calls an API with credentials you manage yourself — OAuth2 client credentials, an API key header, basic auth, or a bearer token. You can also use a type: basic profile to password-gate a public form.

Works with secret blocks (profiles read values from one via secrets:) and type: http nodes. For Swirls-brokered OAuth (Slack, Linear, …), use a connection instead — no profile and no vault entry required.

Profiles are about your system reaching out (or gating a form submission). For who may invoke agents and workflows, see Access.

auth

Reference a secret block via secrets:; field identifiers (client_id, token, key, etc.) must match names listed in that block's vars. type: is required and takes exactly four values:

The oauth type is the client-credentials flow: the runtime posts to token_url and sends the resulting access token as Authorization: Bearer, cached until it expires. For an interactive OAuth consent flow (Slack, Linear, and other supported providers), that is a connection, not an auth block.

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
}

Outbound: HTTP auth:

On type: http nodes, set auth: to attach a credential profile to the request. Set connection: instead when Swirls should broker OAuth — never both on the same node.

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

The runtime applies the profile (token exchange, header injection, or Basic encoding). Do not duplicate that work in headers with a hand-built Authorization value if auth: can do it. Avoid hyphenated keys in literal headers objects — they break the parser (see Syntax).

Inbound: form auth:

On form blocks, auth: gates who may load or submit the form. Only a profile with type: basic is valid. The Triggers service requires a valid Authorization: Basic header before rendering or accepting submissions.

Visibility is enforced first: auth: on an internal form has no effect because the form already returns 404. See Resources — Forms.

form gated_contact {
  label: "Gated contact form"
  visibility: public
  auth: basic_ex
  schema: contact_payload
}

Webhooks are gated differently. A webhook block takes a secret: <block>.<VAR> and header: "<Name>" pair, and the platform compares the inbound header against the shared secret before accepting a POST. Auth blocks are not referenced from webhooks.

Common mistakes

• Any other type value. Only oauth, api_key, basic, and bearer exist. For a Swirls-brokered grant, use a connection, not an auth block.
• Field values that are not vars. client_id, key, username, token, and friends must each name a var declared in the referenced secret block's vars.
• Setting both header: and query_param: on an api_key profile. Pick exactly one.
• auth: on a non-HTTP node. Only http nodes take auth:; integration nodes take connection: only.
• Gating a form with a non-basic profile. Form auth: accepts type: basic only.

Further reading

• Connections overview: the three levels — secrets, profiles, brokered OAuth
• Connection blocks: brokered OAuth with no credentials in the file or vault
• Node types: http node fields