Skip to main content
POST
Create a connection

Authorizations

Authorization
string
header
required

workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens

Headers

akua-context
string

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.

Required string length: 1 - 53
Example:

"ws_j572abc123def456"

idempotency-key
string

Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.

Required string length: 1 - 64
Example:

"create-prod-2026-05-07"

Body

application/json
connector
string
required

A connector's stable slug.

Pattern: ^[a-z0-9][a-z0-9_-]{0,63}$
Example:

"openai"

vault_id
string

The vault that holds the connection. Defaults to the Workspace's default vault, or to the vault named by Akua-Context.

Pattern: ^vlt_[^\s/]{1,64}$
Example:

"vlt_j572abc123def456"

name
string
Required string length: 1 - 100
owner
object

Defaults to the calling user. A user owner is always the authenticated caller, never a client-supplied id.

Response

Connection created

id
string
required

A connection id

Pattern: ^conn_[^\s/]{1,64}$
Example:

"conn_j572abc123def456"

vault_id
string
required

A vault id

Pattern: ^vlt_[^\s/]{1,64}$
Example:

"vlt_j572abc123def456"

connector
string
required

A connector's stable slug.

Pattern: ^[a-z0-9][a-z0-9_-]{0,63}$
Example:

"openai"

name
string
required
Required string length: 1 - 100
owner
object
required

Who owns the connection: the Workspace (a shared account), one user (their own account) or an end customer user in a reseller vault.

state
enum<string>
required
Available options:
PENDING_CONSENT,
CONNECTED,
REAUTH_REQUIRED,
REVOKING,
REVOKED,
ERROR
created_at
integer
required

Unix timestamp (seconds)

Required range: x >= 0
connect_session
object | null
required

The link the owner opens to complete the connection. Null when the connection is already connected or revoked.