---
title: "Create a new project connection"
method: POST
path: "/v1/projects/{projectId}/connections"
tags: ["Connections"]
---

# Create a new project connection

`POST /v1/projects/{projectId}/connections`

Creates a new connection within the specified project. Where a connection requires sensitive information such as a password or authorisation code, that must be created in the relevant secret vault prior to creating a connection. The name of that secret (and, where relevant, key within the secret) is then passed as part of the connection configuration.

For an example of how to use this endpoint as part of automating the provisioning and management of projects, see https://docs.maia.ai/docs/api-reference/provisioning-a-project

## Path parameters

- `projectId` string, required

## Request body

- CreateConnectionRequest — The connection creation request containing all necessary details
  - `authProvider` string — The authentication provider
  - `authType` 'GENERIC_SECRET' | 'CLOUD_PROVIDER_SECRET' | 'OAUTH_USER_TOKENS' | 'OAUTH_AUTHORIZATION_CODE' | 'OAUTH_CLIENT_CRED' | 'COMPOSITE_TOKEN' | 'OAUTH_1_0_X_ADS', required — The kind of secret being referenced. See the combinations table in the operation description for valid values per connection type.
  - `connectionDetails` ConnectionDetails
    - `connectionProperties` union — Connection properties as determined by the combination of platformConnectionType, authProvider and authType.
      - CloudPlatformCredentialsConnectionProperties — Connection properties for cloud platform credentials connections
        - `credentialSecretName` string — The name of the secret containing the cloud platform credentials
      - ComponentBasicConnectionProperties — Connection properties for component basic connections
        - `secretKey` string — Optional key within the secret
        - `secretName` string, required — The name of the secret
    - `description` string — Optional description of the connection
    - `secretsLocation` union — Vault location for secrets. Allows you to specify the type of vault such as AWS, Azure, GCP, or Snowflake, and any supplementary properties such as region (AWS), vaultName (Azure, Snowflake), or gcpProjectId (GCP). Optional for empty project connections that rely solely on environment overrides.
      - AwsVaultLocation
        - `type` 'AWS_SECRET_MANAGER' | 'AZURE_SECRET_MANAGER' | 'GCP_SECRET_MANAGER' | 'MATILLION_CUSTOMER_VAULT' | 'DEFAULT_SECRET_VAULT'
        - `region` string
      - AzureVaultLocation
        - `type` 'AWS_SECRET_MANAGER' | 'AZURE_SECRET_MANAGER' | 'GCP_SECRET_MANAGER' | 'MATILLION_CUSTOMER_VAULT' | 'DEFAULT_SECRET_VAULT'
        - `vaultName` string
      - DefaultVaultLocation
        - `type` 'AWS_SECRET_MANAGER' | 'AZURE_SECRET_MANAGER' | 'GCP_SECRET_MANAGER' | 'MATILLION_CUSTOMER_VAULT' | 'DEFAULT_SECRET_VAULT'
      - GcpVaultLocation
        - `type` 'AWS_SECRET_MANAGER' | 'AZURE_SECRET_MANAGER' | 'GCP_SECRET_MANAGER' | 'MATILLION_CUSTOMER_VAULT' | 'DEFAULT_SECRET_VAULT'
        - `gcpProjectId` string
      - MatillionHostedVaultLocation
        - `type` 'AWS_SECRET_MANAGER' | 'AZURE_SECRET_MANAGER' | 'GCP_SECRET_MANAGER' | 'MATILLION_CUSTOMER_VAULT' | 'DEFAULT_SECRET_VAULT'
  - `name` string, required — The name of the connection
  - `platformConnectionType` 'COMPONENT_BASIC' | 'CLOUD_PLATFORM_CREDENTIALS', required — The different types of connection that can be created: - `COMPONENT_BASIC` — connect a component to a data source, API, or SaaS application using a secret stored in your secrets manager. - `CLOUD_PLATFORM_CREDENTIALS` — give a project access to a cloud provider (AWS, Azure, GCP) using cloud credentials stored in your secrets manager.

## Response `201`

Connection created successfully

- ProjectConnectionResponse
  - `authProvider` string — The authentication provider
  - `authType` 'GENERIC_SECRET' | 'CLOUD_PROVIDER_SECRET' | 'OAUTH_USER_TOKENS' | 'OAUTH_AUTHORIZATION_CODE' | 'OAUTH_CLIENT_CRED' | 'COMPOSITE_TOKEN' | 'OAUTH_1_0_X_ADS' — The authentication type
  - `connectionDetails` ConnectionDetailsResponse
    - `connectionProperties` union — Connection properties as determined by the combination of platformConnectionType, authProvider and authType.
      - CloudPlatformCredentialsConnectionProperties — Connection properties for cloud platform credentials connections
        - `credentialSecretName` string — The name of the secret containing the cloud platform credentials
      - ComponentBasicConnectionProperties — Connection properties for component basic connections
        - `secretKey` string — Optional key within the secret
        - `secretName` string, required — The name of the secret
    - `description` string — Optional description of the connection
    - `secretsLocation` union — Vault location for secrets. Allows you to specify the type of vault such as AWS, Azure, GCP, or Snowflake, and any supplementary properties such as region (AWS), vaultName (Azure, Snowflake), or gcpProjectId (GCP). Optional for empty project connections that rely solely on environment overrides.
      - AwsVaultLocation
        - `type` 'AWS_SECRET_MANAGER' | 'AZURE_SECRET_MANAGER' | 'GCP_SECRET_MANAGER' | 'MATILLION_CUSTOMER_VAULT' | 'DEFAULT_SECRET_VAULT'
        - `region` string
      - AzureVaultLocation
        - `type` 'AWS_SECRET_MANAGER' | 'AZURE_SECRET_MANAGER' | 'GCP_SECRET_MANAGER' | 'MATILLION_CUSTOMER_VAULT' | 'DEFAULT_SECRET_VAULT'
        - `vaultName` string
      - DefaultVaultLocation
        - `type` 'AWS_SECRET_MANAGER' | 'AZURE_SECRET_MANAGER' | 'GCP_SECRET_MANAGER' | 'MATILLION_CUSTOMER_VAULT' | 'DEFAULT_SECRET_VAULT'
      - GcpVaultLocation
        - `type` 'AWS_SECRET_MANAGER' | 'AZURE_SECRET_MANAGER' | 'GCP_SECRET_MANAGER' | 'MATILLION_CUSTOMER_VAULT' | 'DEFAULT_SECRET_VAULT'
        - `gcpProjectId` string
      - MatillionHostedVaultLocation
        - `type` 'AWS_SECRET_MANAGER' | 'AZURE_SECRET_MANAGER' | 'GCP_SECRET_MANAGER' | 'MATILLION_CUSTOMER_VAULT' | 'DEFAULT_SECRET_VAULT'
  - `createdBy` string — The user who created the connection
  - `createdDate` string, date-time — The date and time when the connection was created
  - `name` string — The name of the connection
  - `platformConnectionType` 'COMPONENT_BASIC' | 'CLOUD_PLATFORM_CREDENTIALS' — The different types of connection that can be created: - `COMPONENT_BASIC` — connect a component to a data source, API, or SaaS application using a secret stored in your secrets manager. - `CLOUD_PLATFORM_CREDENTIALS` — give a project access to a cloud provider (AWS, Azure, GCP) using cloud credentials stored in your secrets manager.
  - `projectId` string, uuid — The project ID this connection belongs to

## Other responses

- `400` — Bad Request
- `403` — Unauthorized
- `409` — Connection name needs to be unique in the project.
- `422` — Unprocessable Entity
- `500` — Unexpected error occurred

---

[API](https://skmtc.net/maia/apis/maia-public-rest-api.md) · [All operations](https://skmtc.net/maia/apis/maia-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/maia/maia-public-rest-api/versions/6239825f68eb/schema)