Create a connection

The connection type and auth config must match -- for example, a GIT_TOKEN connection requires a GitTokenAuth config. The server validates connectivity on creation when possible and sets the initial status accordingly.

Scope: connection:write

Authorization

bearerAuth

AuthorizationBearer <token>

Personal Access Token (PAT) or Service Access Token (SAT). Pass the token in the Authorization header: Bearer adm_pat_...

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

aws_federation*

AWSFederationConfig holds the IAM role configuration for OIDC-based authentication to AWS services (ECR, S3, Terraform provider).

Setup: Create an IAM Role with a trust policy that accepts Admiral's OIDC issuer (https://oidc.admiral.io) and conditions on the tenant_id claim matching your Admiral tenant.

name?name

URL-safe, human-readable identifier (e.g., "github-org", "ecr-prod"). Must be unique within the tenant.

Match^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$

Length1 <= length <= 63

description?description

Optional description of the connection's purpose.

Lengthlength <= 1024

type?type

The type of external system and authentication mechanism.

Value in

"CONNECTION_TYPE_UNSPECIFIED" | "CONNECTION_TYPE_GIT_TOKEN" | "CONNECTION_TYPE_GIT_SSH" | "CONNECTION_TYPE_GIT_GITHUB_APP" | "CONNECTION_TYPE_HELM_HTTP" | "CONNECTION_TYPE_OCI_BASIC" | "CONNECTION_TYPE_CLOUD_AWS" | "CONNECTION_TYPE_CLOUD_GCP" | "CONNECTION_TYPE_CLOUD_AZURE" | "CONNECTION_TYPE_CLOUD_AWS_STATIC" | "CONNECTION_TYPE_CLOUD_GCP_STATIC" | "CONNECTION_TYPE_CLOUD_AZURE_STATIC" | "CONNECTION_TYPE_TERRAFORM_REGISTRY" | "CONNECTION_TYPE_S3" | "CONNECTION_TYPE_GCS"

labels?

Arbitrary key-value labels for organizing and filtering connections.

Propertiesproperties <= 64

aws_static*Deprecated

AWSStaticAuth holds static AWS credentials. Prefer AWSFederationConfig (OIDC) instead. Static credentials require manual rotation and present a security risk if compromised.

name?name

URL-safe, human-readable identifier (e.g., "github-org", "ecr-prod"). Must be unique within the tenant.

Match^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$

Length1 <= length <= 63

description?description

Optional description of the connection's purpose.

Lengthlength <= 1024

type?type

The type of external system and authentication mechanism.

Value in

"CONNECTION_TYPE_UNSPECIFIED" | "CONNECTION_TYPE_GIT_TOKEN" | "CONNECTION_TYPE_GIT_SSH" | "CONNECTION_TYPE_GIT_GITHUB_APP" | "CONNECTION_TYPE_HELM_HTTP" | "CONNECTION_TYPE_OCI_BASIC" | "CONNECTION_TYPE_CLOUD_AWS" | "CONNECTION_TYPE_CLOUD_GCP" | "CONNECTION_TYPE_CLOUD_AZURE" | "CONNECTION_TYPE_CLOUD_AWS_STATIC" | "CONNECTION_TYPE_CLOUD_GCP_STATIC" | "CONNECTION_TYPE_CLOUD_AZURE_STATIC" | "CONNECTION_TYPE_TERRAFORM_REGISTRY" | "CONNECTION_TYPE_S3" | "CONNECTION_TYPE_GCS"

labels?

Arbitrary key-value labels for organizing and filtering connections.

Propertiesproperties <= 64

azure_federation*

AzureFederationConfig holds the federated credential configuration for OIDC-based authentication to Azure services (ACR, Terraform).

Setup: Create a Federated Identity Credential on your Azure AD app registration that trusts Admiral's OIDC issuer with your tenant_id claim.

name?name

URL-safe, human-readable identifier (e.g., "github-org", "ecr-prod"). Must be unique within the tenant.

Match^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$

Length1 <= length <= 63

description?description

Optional description of the connection's purpose.

Lengthlength <= 1024

type?type

The type of external system and authentication mechanism.

Value in

"CONNECTION_TYPE_UNSPECIFIED" | "CONNECTION_TYPE_GIT_TOKEN" | "CONNECTION_TYPE_GIT_SSH" | "CONNECTION_TYPE_GIT_GITHUB_APP" | "CONNECTION_TYPE_HELM_HTTP" | "CONNECTION_TYPE_OCI_BASIC" | "CONNECTION_TYPE_CLOUD_AWS" | "CONNECTION_TYPE_CLOUD_GCP" | "CONNECTION_TYPE_CLOUD_AZURE" | "CONNECTION_TYPE_CLOUD_AWS_STATIC" | "CONNECTION_TYPE_CLOUD_GCP_STATIC" | "CONNECTION_TYPE_CLOUD_AZURE_STATIC" | "CONNECTION_TYPE_TERRAFORM_REGISTRY" | "CONNECTION_TYPE_S3" | "CONNECTION_TYPE_GCS"

labels?

Arbitrary key-value labels for organizing and filtering connections.

Propertiesproperties <= 64

azure_static*Deprecated

AzureStaticAuth holds static Azure service principal credentials. Prefer AzureFederationConfig (Federated Credential) instead.

name?name

URL-safe, human-readable identifier (e.g., "github-org", "ecr-prod"). Must be unique within the tenant.

Match^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$

Length1 <= length <= 63

description?description

Optional description of the connection's purpose.

Lengthlength <= 1024

type?type

The type of external system and authentication mechanism.

Value in

"CONNECTION_TYPE_UNSPECIFIED" | "CONNECTION_TYPE_GIT_TOKEN" | "CONNECTION_TYPE_GIT_SSH" | "CONNECTION_TYPE_GIT_GITHUB_APP" | "CONNECTION_TYPE_HELM_HTTP" | "CONNECTION_TYPE_OCI_BASIC" | "CONNECTION_TYPE_CLOUD_AWS" | "CONNECTION_TYPE_CLOUD_GCP" | "CONNECTION_TYPE_CLOUD_AZURE" | "CONNECTION_TYPE_CLOUD_AWS_STATIC" | "CONNECTION_TYPE_CLOUD_GCP_STATIC" | "CONNECTION_TYPE_CLOUD_AZURE_STATIC" | "CONNECTION_TYPE_TERRAFORM_REGISTRY" | "CONNECTION_TYPE_S3" | "CONNECTION_TYPE_GCS"

labels?

Arbitrary key-value labels for organizing and filtering connections.

Propertiesproperties <= 64

bearer_token*

BearerTokenAuth holds a bearer token for systems that use token-based authentication (e.g., private Terraform registries).

name?name

URL-safe, human-readable identifier (e.g., "github-org", "ecr-prod"). Must be unique within the tenant.

Match^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$

Length1 <= length <= 63

description?description

Optional description of the connection's purpose.

Lengthlength <= 1024

type?type

The type of external system and authentication mechanism.

Value in

"CONNECTION_TYPE_UNSPECIFIED" | "CONNECTION_TYPE_GIT_TOKEN" | "CONNECTION_TYPE_GIT_SSH" | "CONNECTION_TYPE_GIT_GITHUB_APP" | "CONNECTION_TYPE_HELM_HTTP" | "CONNECTION_TYPE_OCI_BASIC" | "CONNECTION_TYPE_CLOUD_AWS" | "CONNECTION_TYPE_CLOUD_GCP" | "CONNECTION_TYPE_CLOUD_AZURE" | "CONNECTION_TYPE_CLOUD_AWS_STATIC" | "CONNECTION_TYPE_CLOUD_GCP_STATIC" | "CONNECTION_TYPE_CLOUD_AZURE_STATIC" | "CONNECTION_TYPE_TERRAFORM_REGISTRY" | "CONNECTION_TYPE_S3" | "CONNECTION_TYPE_GCS"

labels?

Arbitrary key-value labels for organizing and filtering connections.

Propertiesproperties <= 64

gcp_federation*

GCPFederationConfig holds the Workload Identity Federation configuration for OIDC-based authentication to GCP services (Artifact Registry, GCS, Terraform).

Setup: Create a Workload Identity Pool and Provider that trusts Admiral's OIDC issuer, then grant the service account access to the required resources.

name?name

URL-safe, human-readable identifier (e.g., "github-org", "ecr-prod"). Must be unique within the tenant.

Match^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$

Length1 <= length <= 63

description?description

Optional description of the connection's purpose.

Lengthlength <= 1024

type?type

The type of external system and authentication mechanism.

Value in

"CONNECTION_TYPE_UNSPECIFIED" | "CONNECTION_TYPE_GIT_TOKEN" | "CONNECTION_TYPE_GIT_SSH" | "CONNECTION_TYPE_GIT_GITHUB_APP" | "CONNECTION_TYPE_HELM_HTTP" | "CONNECTION_TYPE_OCI_BASIC" | "CONNECTION_TYPE_CLOUD_AWS" | "CONNECTION_TYPE_CLOUD_GCP" | "CONNECTION_TYPE_CLOUD_AZURE" | "CONNECTION_TYPE_CLOUD_AWS_STATIC" | "CONNECTION_TYPE_CLOUD_GCP_STATIC" | "CONNECTION_TYPE_CLOUD_AZURE_STATIC" | "CONNECTION_TYPE_TERRAFORM_REGISTRY" | "CONNECTION_TYPE_S3" | "CONNECTION_TYPE_GCS"

labels?

Arbitrary key-value labels for organizing and filtering connections.

Propertiesproperties <= 64

gcp_static*Deprecated

GCPStaticAuth holds a static GCP service account key. Prefer GCPFederationConfig (Workload Identity) instead.

name?name

URL-safe, human-readable identifier (e.g., "github-org", "ecr-prod"). Must be unique within the tenant.

Match^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$

Length1 <= length <= 63

description?description

Optional description of the connection's purpose.

Lengthlength <= 1024

type?type

The type of external system and authentication mechanism.

Value in

"CONNECTION_TYPE_UNSPECIFIED" | "CONNECTION_TYPE_GIT_TOKEN" | "CONNECTION_TYPE_GIT_SSH" | "CONNECTION_TYPE_GIT_GITHUB_APP" | "CONNECTION_TYPE_HELM_HTTP" | "CONNECTION_TYPE_OCI_BASIC" | "CONNECTION_TYPE_CLOUD_AWS" | "CONNECTION_TYPE_CLOUD_GCP" | "CONNECTION_TYPE_CLOUD_AZURE" | "CONNECTION_TYPE_CLOUD_AWS_STATIC" | "CONNECTION_TYPE_CLOUD_GCP_STATIC" | "CONNECTION_TYPE_CLOUD_AZURE_STATIC" | "CONNECTION_TYPE_TERRAFORM_REGISTRY" | "CONNECTION_TYPE_S3" | "CONNECTION_TYPE_GCS"

labels?

Arbitrary key-value labels for organizing and filtering connections.

Propertiesproperties <= 64

git_github_app*

GitHubAppAuth holds GitHub App credentials for Git operations. Preferred over personal tokens for organizations -- provides granular repository permissions and a better audit trail.

name?name

URL-safe, human-readable identifier (e.g., "github-org", "ecr-prod"). Must be unique within the tenant.

Match^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$

Length1 <= length <= 63

description?description

Optional description of the connection's purpose.

Lengthlength <= 1024

type?type

The type of external system and authentication mechanism.

Value in

"CONNECTION_TYPE_UNSPECIFIED" | "CONNECTION_TYPE_GIT_TOKEN" | "CONNECTION_TYPE_GIT_SSH" | "CONNECTION_TYPE_GIT_GITHUB_APP" | "CONNECTION_TYPE_HELM_HTTP" | "CONNECTION_TYPE_OCI_BASIC" | "CONNECTION_TYPE_CLOUD_AWS" | "CONNECTION_TYPE_CLOUD_GCP" | "CONNECTION_TYPE_CLOUD_AZURE" | "CONNECTION_TYPE_CLOUD_AWS_STATIC" | "CONNECTION_TYPE_CLOUD_GCP_STATIC" | "CONNECTION_TYPE_CLOUD_AZURE_STATIC" | "CONNECTION_TYPE_TERRAFORM_REGISTRY" | "CONNECTION_TYPE_S3" | "CONNECTION_TYPE_GCS"

labels?

Arbitrary key-value labels for organizing and filtering connections.

Propertiesproperties <= 64

git_ssh*

GitSSHAuth holds SSH key credentials for Git operations.

name?name

URL-safe, human-readable identifier (e.g., "github-org", "ecr-prod"). Must be unique within the tenant.

Match^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$

Length1 <= length <= 63

description?description

Optional description of the connection's purpose.

Lengthlength <= 1024

type?type

The type of external system and authentication mechanism.

Value in

"CONNECTION_TYPE_UNSPECIFIED" | "CONNECTION_TYPE_GIT_TOKEN" | "CONNECTION_TYPE_GIT_SSH" | "CONNECTION_TYPE_GIT_GITHUB_APP" | "CONNECTION_TYPE_HELM_HTTP" | "CONNECTION_TYPE_OCI_BASIC" | "CONNECTION_TYPE_CLOUD_AWS" | "CONNECTION_TYPE_CLOUD_GCP" | "CONNECTION_TYPE_CLOUD_AZURE" | "CONNECTION_TYPE_CLOUD_AWS_STATIC" | "CONNECTION_TYPE_CLOUD_GCP_STATIC" | "CONNECTION_TYPE_CLOUD_AZURE_STATIC" | "CONNECTION_TYPE_TERRAFORM_REGISTRY" | "CONNECTION_TYPE_S3" | "CONNECTION_TYPE_GCS"

labels?

Arbitrary key-value labels for organizing and filtering connections.

Propertiesproperties <= 64

git_token*

GitTokenAuth holds HTTPS token credentials for Git operations.

name?name

URL-safe, human-readable identifier (e.g., "github-org", "ecr-prod"). Must be unique within the tenant.

Match^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$

Length1 <= length <= 63

description?description

Optional description of the connection's purpose.

Lengthlength <= 1024

type?type

The type of external system and authentication mechanism.

Value in

"CONNECTION_TYPE_UNSPECIFIED" | "CONNECTION_TYPE_GIT_TOKEN" | "CONNECTION_TYPE_GIT_SSH" | "CONNECTION_TYPE_GIT_GITHUB_APP" | "CONNECTION_TYPE_HELM_HTTP" | "CONNECTION_TYPE_OCI_BASIC" | "CONNECTION_TYPE_CLOUD_AWS" | "CONNECTION_TYPE_CLOUD_GCP" | "CONNECTION_TYPE_CLOUD_AZURE" | "CONNECTION_TYPE_CLOUD_AWS_STATIC" | "CONNECTION_TYPE_CLOUD_GCP_STATIC" | "CONNECTION_TYPE_CLOUD_AZURE_STATIC" | "CONNECTION_TYPE_TERRAFORM_REGISTRY" | "CONNECTION_TYPE_S3" | "CONNECTION_TYPE_GCS"

labels?

Arbitrary key-value labels for organizing and filtering connections.

Propertiesproperties <= 64

helm_http*

HelmHTTPAuth holds basic auth credentials for classic Helm HTTP repositories.

name?name

URL-safe, human-readable identifier (e.g., "github-org", "ecr-prod"). Must be unique within the tenant.

Match^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$

Length1 <= length <= 63

description?description

Optional description of the connection's purpose.

Lengthlength <= 1024

type?type

The type of external system and authentication mechanism.

Value in

"CONNECTION_TYPE_UNSPECIFIED" | "CONNECTION_TYPE_GIT_TOKEN" | "CONNECTION_TYPE_GIT_SSH" | "CONNECTION_TYPE_GIT_GITHUB_APP" | "CONNECTION_TYPE_HELM_HTTP" | "CONNECTION_TYPE_OCI_BASIC" | "CONNECTION_TYPE_CLOUD_AWS" | "CONNECTION_TYPE_CLOUD_GCP" | "CONNECTION_TYPE_CLOUD_AZURE" | "CONNECTION_TYPE_CLOUD_AWS_STATIC" | "CONNECTION_TYPE_CLOUD_GCP_STATIC" | "CONNECTION_TYPE_CLOUD_AZURE_STATIC" | "CONNECTION_TYPE_TERRAFORM_REGISTRY" | "CONNECTION_TYPE_S3" | "CONNECTION_TYPE_GCS"

labels?

Arbitrary key-value labels for organizing and filtering connections.

Propertiesproperties <= 64

oci_basic*

BasicAuth holds username/password credentials for OCI registries and other systems that use basic authentication.

name?name

URL-safe, human-readable identifier (e.g., "github-org", "ecr-prod"). Must be unique within the tenant.

Match^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$

Length1 <= length <= 63

description?description

Optional description of the connection's purpose.

Lengthlength <= 1024

type?type

The type of external system and authentication mechanism.

Value in

"CONNECTION_TYPE_UNSPECIFIED" | "CONNECTION_TYPE_GIT_TOKEN" | "CONNECTION_TYPE_GIT_SSH" | "CONNECTION_TYPE_GIT_GITHUB_APP" | "CONNECTION_TYPE_HELM_HTTP" | "CONNECTION_TYPE_OCI_BASIC" | "CONNECTION_TYPE_CLOUD_AWS" | "CONNECTION_TYPE_CLOUD_GCP" | "CONNECTION_TYPE_CLOUD_AZURE" | "CONNECTION_TYPE_CLOUD_AWS_STATIC" | "CONNECTION_TYPE_CLOUD_GCP_STATIC" | "CONNECTION_TYPE_CLOUD_AZURE_STATIC" | "CONNECTION_TYPE_TERRAFORM_REGISTRY" | "CONNECTION_TYPE_S3" | "CONNECTION_TYPE_GCS"

labels?

Arbitrary key-value labels for organizing and filtering connections.

Propertiesproperties <= 64

Response Body

`application/json`

curl -X POST "https://admiral.example.com/api/v1/connections" \  -H "Content-Type: application/json" \  -d '{    "aws_federation": {}  }'

{  "connection": {    "id": "b8c9d0e1-2345-6fab-cdef-0123456789ab",    "name": "ecr-prod",    "description": "Read-only access to production ECR registry for container image pulls.",    "type": "CONNECTION_TYPE_DOCKER_REGISTRY",    "status": "CONNECTION_STATUS_ACTIVE",    "labels": {      "cloud": "aws",      "team": "platform"    },    "created_by": "d290f1ee-6c54-4b01-90e6-d701748f0851",    "updated_by": "d290f1ee-6c54-4b01-90e6-d701748f0851",    "created_at": "2025-07-20T14:00:00Z",    "updated_at": "2025-10-15T10:30:00Z",    "last_tested_at": "2025-11-01T08:00:00Z"  }}

Create a connection

Authorization

Request Body

Response Body

200application/json

`application/json`