Connect an upstream provider

A Connector defines a configured upstream capability contract. A Connection is one User’s authenticated upstream account or personal credential for that Connector. Connecting does not itself grant an Application access.

Prerequisites

• The administrator has configured an active Connector and attached it to the target gateway.
• The Connector supports user OAuth or a supported personal credential mode.
• The User has an active Axec browser session.

Connect during authorization

1. Start User-delegated authorization for the exact gateway Resource.
2. Optionally select the Connector with an exact repeated allowed_connector value. An explicit selection cannot be skipped.
3. Follow the backend-owned authorization continuation. When it reports a missing Connection, submit the displayed connection action as a native browser form so the 302 or 303 resumes the top-level flow.
4. For OAuth, authorize Axec at the upstream provider. For a personal credential, submit only the credential kind and fields defined by the configured Connector.
5. Return to Axec, review the displayed authority, and consent.

For a standalone OAuth connection, start the same user-owned lifecycle with POST /api/v1/me/connectors/{connector_id}/connections/start; the provider callback persists the Connection before a later authorization uses it.

Expected result

Axec stores one active Connection for the User and Connector, including safe account metadata, normalized scopes, capability discovery, and encrypted credential material. The Application receives no refresh token, static secret, or vaulted value. Consent later creates a Grant that pins this exact Connection ID.

Replacement and failure behavior

Reconnecting revokes the old Connection and inserts a replacement with a new identity. Existing Grants stay pinned to the old, now unusable Connection and never inherit the replacement silently. If discovery, callback validation, or credential storage fails, no usable Connection should be assumed; resume the backend continuation and inspect its current state.

This guide is provider-neutral by design. The configured Connector contract, not a provider catalog page, defines the supported scopes and capabilities.