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.

app.yaml
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).
app.yaml
- 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).
app.yaml
- 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.
app.yaml
- 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.
app.yaml
- 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:

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

Last updated August 11, 2026

Edit this pageReport an issue

This documentation was written with AI, so errors or outdated content are possible. Sovrium is in beta. Contributions and corrections are welcome.

Built with Sovrium