dots.v2.actionGateway.connections.post()

Generated on 5 Nov 2026 from DoTs version v1.23.0

Usage

client.v2.actionGateway.connections.post(body: Connection_create, requestConfiguration?: RequestConfiguration<object>): Promise<undefined | Connection_response>

Description

Connects one of your users, identified by user_id, to a provider so tools can act on their account. An OAuth connection starts pending, and authorization carries the URL to send the user to; read the connection until it is active or expired. A connection through a team API-key credential is active immediately. Register the API key with POST /v2/action-gateway/provider-credentials first, then set credential.team_credential.credential_id to the returned credential.id.

There is one connection per provider and user_id for each DigitalOcean user who creates connections. Repeating the request returns the existing connection when its scopes cover the request, reusing a pending connection’s link, and restarts an expired or revoked connection under the same ID. Requesting scopes beyond an existing connection’s, or a different credential, returns 400 until that connection is deleted.

Parameters

provider string required

Example: jira

Required provider slug, from the provider list.

userId string required

Example: alice

Required. Your identifier for the user the connection acts for: 1 to 64 characters from [A-Za-z0-9._-]. A session whose actor_id equals it uses this connection.

scopes array of strings optional

Example: ["write:jira-work"]

Optional OAuth scopes to request. Defaults to every scope the provider offers; scopes outside that set are rejected. Ignored for API-key credentials.

connectionParameters object optional

Example: {"site_url": "https://example.atlassian.net"}

Values for the provider's connection_parameters, validated against their specifications.

credential object optional

Optional credential to connect through. Omitted uses DigitalOcean's shared OAuth application.

Show child properties
digitaloceanOauth object optional

Use DigitalOcean's shared OAuth application.

teamCredential object optional

Use one of your team's provider credentials.

Additional nested properties are not shown.

network object optional

Optional private network for the connection's calls. Requires VPC networking to be enabled for your account (403 otherwise).

Show child properties
vpc object optional

Route through a VPC.

Additional nested properties are not shown.

Response Example

Show Response Example
{
  "connection": {
    "id": "39f9f768-a7f9-4c91-9557-3328c53dd054",
    "provider": "jira",
    "provider_display_name": "Jira",
    "user_id": "alice",
    "status": "pending",
    "created_at": "2026-07-14T00:50:00Z",
    "updated_at": "2026-07-14T00:50:00Z",
    "revoked_at": null,
    "connection_parameters": {
      "site_url": "https://example.atlassian.net"
    },
    "credential_kind": "digitalocean_oauth",
    "credential_id": "",
    "network": null,
    "scopes": [
      "write:jira-work"
    ],
    "granted_at": null,
    "oauth": {
      "scopes": [
        "write:jira-work"
      ],
      "granted_at": null
    }
  },
  "authorization": {
    "status": "requires_authorization",
    "connect_url": "https://cloud.digitalocean.com/security/connectlinks/confirm?token=eyJhbGciOi",
    "verification_code": "97rwxzcy",
    "expires_at": "2026-07-14T01:00:00Z"
  }
}

More Information

See /v2/action-gateway/connections in the API reference for additional detail on responses, headers, parameters, and more.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.