Skip to main content
View as Markdown

Connections

Connections store credentials for external services once under the top-level app.connections[] array, then reference them from HTTP and AI actions via $connection.NAME. Sovrium attaches the right authentication on each request and — for OAuth2 — refreshes tokens automatically.

connections:
  - name: crm-oauth
    label: Acme CRM
    type: oauth2
    props:
      provider: google
      clientId: $env.GOOGLE_CLIENT_ID
      clientSecret: $env.GOOGLE_CLIENT_SECRET
      scopes: [openid, email, profile]

Every connection shares three base fields and a typed props object:

Property Description
name Kebab-case identifier (^[a-z][a-z0-9-]*$, max 100). Referenced as $connection.NAME. Required.
label Human-readable label.
description What the connection is for.
type oauth2 / apiKey / basic / bearer. Required. Determines the props shape.
props Type-specific credential config (below). Secret values should use $env.VAR.

Connection names must be unique across the app.

OAuth2

Full OAuth2 with authorization-code or client-credentials grants, PKCE, token refresh, and per-user vs shared (app) tokens.

props field Description
provider Known provider shorthand (e.g. google, github, slack). May infer auth/token URLs.
clientId OAuth2 client ID (supports $env.VAR). Required.
clientSecret OAuth2 client secret (supports $env.VAR). Required.
authorizationUrl Authorization endpoint (required for custom providers).
tokenUrl Token endpoint (required for custom providers).
scopes Array of scopes to request.
redirectUri Redirect URI registered with the provider. Required at runtime — auto-generation is not implemented.
grantType authorizationCode (default) or clientCredentials.
pkce PKCE method: S256 (recommended), plain, or none (default).
audience API audience / resource identifier (e.g. an Auth0 audience URL).
authenticationMethod How client creds are sent on token requests: header (HTTP Basic, RFC 6749 default) or body (form params). Honored by the refresh grant.
extraAuthParams Extra params appended to the authorization URL (e.g. access_type: offline, prompt: consent).
extraTokenParams Extra params appended to token-exchange requests.
scope Connection scope: app (admin-only shared token, default) or user (per-user tokens). 
- name: hubspot
  type: oauth2
  props:
    clientId: $env.HUBSPOT_CLIENT_ID
    clientSecret: $env.HUBSPOT_CLIENT_SECRET
    authorizationUrl: 'https://app.hubspot.com/oauth/authorize'
    tokenUrl: 'https://api.hubapi.com/oauth/v1/token'
    scopes: [crm.objects.contacts.read]
    redirectUri: 'https://myapp.example.com/oauth/callback'
    pkce: S256
    scope: user
    extraAuthParams: { access_type: offline, prompt: consent }

API Key

API key sent in a configurable header, with an optional prefix.

props field Description
key API key value (typically $env.VAR). Required.
header Header name for the key (default X-API-Key).
prefix Prefix before the value in the header (e.g. Bearer, Token). 
- name: github-api
  type: apiKey
  props: { key: $env.GITHUB_TOKEN, header: Authorization, prefix: Bearer }

Basic Auth

HTTP Basic authentication.

props field Description
username Username (supports $env.VAR). Required.
password Password (supports $env.VAR). Required. 
- name: legacy-api
  type: basic
  props: { username: $env.LEGACY_USER, password: $env.LEGACY_PASS }

Bearer Token

A static bearer token sent in the Authorization header.

props field Description
token Bearer token value (typically $env.VAR). Required. 
- name: internal-svc
  type: bearer
  props: { token: $env.INTERNAL_SERVICE_TOKEN }

Referencing a Connection

Attach a connection to an HTTP or AI action via the connection prop:

- name: fetch
  type: http
  operator: get
  props: { url: 'https://api.example.com/me', connection: github-api }