Create a connection
Creates a connection in PENDING_CONSENT and returns a connect session link. The owner opens the link to sign in or enter a key on Connect’s hosted page; the credential never passes through this API.
Authorizations
workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens
Headers
Optional workspace/scope context for the request. Carries a single workspace wire id (ws_…) today. Only needed for broad tokens - a workspace-owned token implies its workspace.
1 - 53"ws_j572abc123def456"
Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.
1 - 64"create-prod-2026-05-07"
Body
A connector's stable slug.
^[a-z0-9][a-z0-9_-]{0,63}$"openai"
The vault that holds the connection. Defaults to the Workspace's default vault, or to the vault named by Akua-Context.
^vlt_[^\s/]{1,64}$"vlt_j572abc123def456"
1 - 100Defaults to the calling user. A user owner is always the authenticated caller, never a client-supplied id.
- Option 1
- Option 2
- Option 3
Response
Connection created
A connection id
^conn_[^\s/]{1,64}$"conn_j572abc123def456"
A vault id
^vlt_[^\s/]{1,64}$"vlt_j572abc123def456"
A connector's stable slug.
^[a-z0-9][a-z0-9_-]{0,63}$"openai"
1 - 100Who owns the connection: the Workspace (a shared account), one user (their own account) or an end customer user in a reseller vault.
- Option 1
- Option 2
- Option 3
PENDING_CONSENT, CONNECTED, REAUTH_REQUIRED, REVOKING, REVOKED, ERROR Unix timestamp (seconds)
x >= 0The link the owner opens to complete the connection. Null when the connection is already connected or revoked.