For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Usage

client.connections.create(
    body={
        "provider": "jira",
        "user_id": "alice",
        "scopes": [...],
        ...,
    },
)

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.

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.

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

connection_parameters 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

digitalocean_oauth object optional

Use DigitalOcean's shared OAuth application.

team_credential object optional

Use one of your team's provider credentials.

Show child properties

credential_id string optional

Example: 8d6f2b1a-3c4e-4d5f-9a8b-7c6d5e4f3a2b

Required. ID of an active provider credential for the same provider that you can use.

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.

Show child properties

vpc_uuid string optional

Example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4

UUID of a VPC owned by your team.

destinations array of objects optional

Private hosts the connection's calls may reach through the VPC. At least one is required.

Show child properties

host string optional

Example: jira.internal.example.com

Host name or IP address. It must resolve only to private addresses.

port integer optional

Example: 443

Port, 1 to 65535.

allowed_ip_cidrs array of strings optional

Example: ['10.116.0.0/20']

Optional CIDR ranges; when set, every address the host resolves to must fall within one of them.

Request Sample

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "provider": "jira",
  "user_id": "alice",
  "scopes": [
    "write:jira-work"
  ],
  "connection_parameters": {
    "site_url": "https://example.atlassian.net"
  },
  "credential": {
    "digitalocean_oauth": {}
  }
}

resp = client.connections.create(body=req)

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.