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

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

```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 }
```

:::callout
**App vs per-user tokens.** `scope: app` stores one shared token usable by admins. `scope: user` issues and stores tokens per end-user, so each user's HTTP/AI actions act as themselves. **Client-credentials** flows (machine-to-machine, no user) set `grantType: clientCredentials`. Token refresh happens automatically; the refresh request honors `authenticationMethod`.
:::

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

```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.** |

```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.** |

```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:

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

## Related Pages

- [HTTP & Webhooks](/en/docs/automation-http-actions) — actions that consume connections.
- [AI Actions](/en/docs/automation-ai-actions) — AI providers authenticated via connections.
- [Environment Variables](/en/docs/automation-env-vars) — `$env` secrets referenced by connection props.
- [Auth Overview](/en/docs/auth-overview) — end-user authentication (distinct from outbound connections).