> ## Documentation Index > Fetch the complete documentation index at: https://docs.maia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a new project connection > 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 ## OpenAPI ````yaml /openapi/public-api-endpoint-reference.yaml post /v1/projects/{projectId}/connections openapi: 3.1.0 info: title: Maia Public REST API version: '1.0' servers: - description: EU1 url: https://eu1.api.matillion.com/dpc - description: US1 url: https://us1.api.matillion.com/dpc security: - bearerAuth: [] tags: - description: Manage Schedules name: Schedules - description: Manage Connections name: Connections - description: Operations for managing Project Variables name: Project Variables - description: Manage Pipelines name: Pipelines - description: Review pipelines against quality rules name: Pipeline Quality Review - description: Execute tests within a project name: Test Execution - description: Manage your AI agent tasks name: AI Agent Tasks - description: SCIM endpoints for user/group permission management name: Directory Integration - description: Publish shared pipeline artifacts name: Shared Pipeline Artifacts - description: Manage Repositories name: Repositories - description: Report on Credit Consumption name: Consumption - description: Manage Artifacts name: Artifacts - description: Operations for data lineage and governance name: Data Lineage - description: Manage Streaming Pipelines name: Streaming Pipelines - description: Execute a pipeline name: Pipeline Execution - description: '' name: Environments - description: '' name: Projects - description: Manage Agents name: Agents - description: Operations for managing Environment-level Overrides of Project Variables name: Project Variable Environment Overrides - description: Query audit events name: Audit Events - description: Connector Profiles name: Connectors paths: /v1/projects/{projectId}/connections: post: tags: - Connections summary: Create a new project connection description: > 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 operationId: createProjectConnection parameters: - description: >- The unique identifier of the project where the connection will be created example: 550e8400-e29b-41d4-a716-446655440002 in: path name: projectId required: true schema: type: string pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ requestBody: content: application/json: examples: CLOUD_PLATFORM_CREDENTIALS Connection: description: >- Creates a connection that gives the project access to AWS using a credentials secret stored in AWS Secrets Manager. Use `azure` or `gcp` for `authProvider` to connect to the other cloud providers. value: name: my-aws-connection platformConnectionType: CLOUD_PLATFORM_CREDENTIALS authProvider: aws authType: CLOUD_PROVIDER_SECRET connectionDetails: description: AWS credentials for the analytics environment secretsLocation: type: AWS_SECRET_MANAGER region: us-east-1 connectionProperties: credentialSecretName: aws-platform-credentials COMPONENT_BASIC Connection: description: Example request for creating a COMPONENT_BASIC connection value: name: my-database-connection platformConnectionType: COMPONENT_BASIC authProvider: NONE authType: GENERIC_SECRET connectionDetails: description: Production database connection for analytics secretsLocation: type: AWS_SECRET_MANAGER region: us-east-1 connectionProperties: secretName: db-credentials secretKey: password COMPONENT_BASIC pointing at OAuth Secret: description: >- Creates a connection that uses an OAuth client-credentials secret. `authType` is set to `OAUTH_CLIENT_CRED` to match the kind of secret being referenced. Use `OAUTH_USER_TOKENS` or `OAUTH_AUTHORIZATION_CODE` for the other OAuth flows. value: name: powerbi-cc-connection platformConnectionType: COMPONENT_BASIC authProvider: powerbi-custom-connector authType: OAUTH_CLIENT_CRED connectionDetails: description: Power BI custom connector OAuth client credentials secretsLocation: type: AWS_SECRET_MANAGER region: eu-west-1 connectionProperties: secretName: powerbi-oauth-creds COMPONENT_BASIC with Default Vault: description: Example request using the account's default vault location value: name: simple-connection platformConnectionType: COMPONENT_BASIC authProvider: NONE authType: GENERIC_SECRET connectionDetails: secretsLocation: type: DEFAULT_SECRET_VAULT connectionProperties: secretName: google-cloud-credentials schema: $ref: '#/components/schemas/CreateConnectionRequest' description: > The parameters platformConnectionType, authProvider and authType are inter-dependent. The valid combinations are: | platformConnectionType | authProvider | authType | Use this for | |---|---|---|---| | COMPONENT_BASIC | NONE | GENERIC_SECRET | Creating simple secret definitions | | COMPONENT_BASIC | _(connector name e.g. `salesforce`)_ | OAUTH_CLIENT_CRED, OAUTH_USER_TOKENS, OAUTH_AUTHORIZATION_CODE | OAuth secrets stored for the named provider | | COMPONENT_BASIC | `netsuite` | COMPOSITE_TOKEN | Creating NetSuite composite-token secrets | | COMPONENT_BASIC | `x-ads` | OAUTH_1_0_X_ADS | Creating X Ads OAuth 1.0 secrets | | CLOUD_PLATFORM_CREDENTIALS | aws | CLOUD_PROVIDER_SECRET | Creating AWS cloud credentials | | CLOUD_PLATFORM_CREDENTIALS | gcp | CLOUD_PROVIDER_SECRET | Creating GCP cloud credentials | | CLOUD_PLATFORM_CREDENTIALS | azure | CLOUD_PROVIDER_SECRET | Creating AZURE cloud credentials | required: true responses: '201': content: application/json: examples: CLOUD_PLATFORM_CREDENTIALS Connection Response: description: >- A successfully created CLOUD_PLATFORM_CREDENTIALS connection that gives the project access to AWS using credentials stored in AWS Secrets Manager. value: id: 550e8400-e29b-41d4-a716-446655440010 name: my-aws-connection platformConnectionType: CLOUD_PLATFORM_CREDENTIALS authProvider: aws authType: CLOUD_PROVIDER_SECRET createdBy: 550e8400-e29b-41d4-a716-446655440001 createdDate: '2024-01-15T10:30:00.123Z' projectId: 550e8400-e29b-41d4-a716-446655440002 connectionDetails: description: AWS credentials for the analytics environment secretsLocation: type: AWS_SECRET_MANAGER region: us-east-1 connectionProperties: credentialSecretName: aws-platform-credentials COMPONENT_BASIC Connection Response: description: >- Example response for a successfully created COMPONENT_BASIC connection value: id: 550e8400-e29b-41d4-a716-446655440000 name: my-database-connection platformConnectionType: COMPONENT_BASIC authProvider: NONE authType: GENERIC_SECRET createdBy: 550e8400-e29b-41d4-a716-446655440001 createdDate: '2024-01-15T10:30:00.123Z' projectId: 550e8400-e29b-41d4-a716-446655440002 connectionDetails: description: Production database connection for analytics secretsLocation: type: AWS_SECRET_MANAGER region: us-east-1 connectionProperties: secretName: db-credentials secretKey: password schema: $ref: '#/components/schemas/ProjectConnectionResponse' description: Connection created successfully '400': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Bad Request '403': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Unauthorized '409': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Connection name needs to be unique in the project. '422': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' description: Unexpected error occurred components: schemas: CreateConnectionRequest: type: object description: The connection creation request containing all necessary details properties: authProvider: type: string description: The authentication provider example: salesforce authType: type: string description: >- The kind of secret being referenced. See the combinations table in the operation description for valid values per connection type. enum: - GENERIC_SECRET - CLOUD_PROVIDER_SECRET - OAUTH_USER_TOKENS - OAUTH_AUTHORIZATION_CODE - OAUTH_CLIENT_CRED - COMPOSITE_TOKEN - OAUTH_1_0_X_ADS example: GENERIC_SECRET connectionDetails: $ref: '#/components/schemas/ConnectionDetails' description: >- Provides the definition of the values of the connection which will vary by connection type. Includes: - Location of any sensitive values (secret location and name) - Any non-sensitive values (url, username) name: type: string description: The name of the connection example: my-secret minLength: 1 platformConnectionType: type: string description: >- 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. enum: - COMPONENT_BASIC - CLOUD_PLATFORM_CREDENTIALS example: COMPONENT_BASIC required: - authType - name - platformConnectionType ProjectConnectionResponse: type: object properties: authProvider: type: string description: The authentication provider example: salesforce authType: type: string description: The authentication type enum: - GENERIC_SECRET - CLOUD_PROVIDER_SECRET - OAUTH_USER_TOKENS - OAUTH_AUTHORIZATION_CODE - OAUTH_CLIENT_CRED - COMPOSITE_TOKEN - OAUTH_1_0_X_ADS example: GENERIC_SECRET connectionDetails: $ref: '#/components/schemas/ConnectionDetailsResponse' description: >- Provides the definition of the values of the connection which will vary by connection type. Includes: - Location of any sensitive values (secret location and name) - Any non-sensitive values (url, username) createdBy: type: string description: The user who created the connection createdDate: type: string format: date-time description: The date and time when the connection was created name: type: string description: The name of the connection example: my-secret platformConnectionType: type: string description: >- 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. enum: - COMPONENT_BASIC - CLOUD_PLATFORM_CREDENTIALS example: COMPONENT_BASIC projectId: type: string format: uuid description: The project ID this connection belongs to ProblemDetail: type: object properties: detail: type: string instance: type: string status: type: integer format: int32 title: type: string type: type: string format: uri violations: type: array items: type: string ConnectionDetails: type: object properties: connectionProperties: description: >- Connection properties as determined by the combination of platformConnectionType, authProvider and authType. oneOf: - $ref: >- #/components/schemas/CloudPlatformCredentialsConnectionProperties - $ref: '#/components/schemas/ComponentBasicConnectionProperties' description: type: string description: Optional description of the connection secretsLocation: description: >- Vault location for secrets. Allows you to specify the type of vault such as AWS, Azure, Snowflake, and any supplementary properties such as region (AWS) or vaultName (Azure, Snowflake). Optional for empty project connections that rely solely on environment overrides. oneOf: - $ref: '#/components/schemas/AwsVaultLocation' - $ref: '#/components/schemas/AzureVaultLocation' - $ref: '#/components/schemas/DefaultVaultLocation' - $ref: '#/components/schemas/GcpVaultLocation' - $ref: '#/components/schemas/MatillionHostedVaultLocation' ConnectionDetailsResponse: type: object properties: connectionProperties: description: >- Connection properties as determined by the combination of platformConnectionType, authProvider and authType. oneOf: - $ref: >- #/components/schemas/CloudPlatformCredentialsConnectionProperties - $ref: '#/components/schemas/ComponentBasicConnectionProperties' description: type: string description: Optional description of the connection secretsLocation: description: >- Vault location for secrets. Allows you to specify the type of vault such as AWS, Azure, Snowflake, and any supplementary properties such as region (AWS) or vaultName (Azure, Snowflake). Optional for empty project connections that rely solely on environment overrides. oneOf: - $ref: '#/components/schemas/AwsVaultLocation' - $ref: '#/components/schemas/AzureVaultLocation' - $ref: '#/components/schemas/DefaultVaultLocation' - $ref: '#/components/schemas/GcpVaultLocation' - $ref: '#/components/schemas/MatillionHostedVaultLocation' CloudPlatformCredentialsConnectionProperties: allOf: - $ref: '#/components/schemas/ConnectionProperties' - type: object properties: credentialSecretName: type: string description: The name of the secret containing the cloud platform credentials example: aws-platform-credentials description: Connection properties for cloud platform credentials connections title: Cloud Platform Credentials ComponentBasicConnectionProperties: allOf: - $ref: '#/components/schemas/ConnectionProperties' - type: object properties: secretKey: type: string description: Optional key within the secret example: password secretName: type: string description: The name of the secret example: some-secret-name minLength: 1 description: Connection properties for component basic connections required: - secretName title: Component Basic AwsVaultLocation: allOf: - $ref: '#/components/schemas/VaultLocation' - type: object properties: region: type: string title: AWS Secrets Manager AzureVaultLocation: allOf: - $ref: '#/components/schemas/VaultLocation' - type: object properties: vaultName: type: string title: Azure Key Vault DefaultVaultLocation: allOf: - $ref: '#/components/schemas/VaultLocation' title: Default Vault GcpVaultLocation: allOf: - $ref: '#/components/schemas/VaultLocation' - type: object properties: gcpProjectId: type: string title: GCP Secret Manager MatillionHostedVaultLocation: allOf: - $ref: '#/components/schemas/VaultLocation' title: Matillion-hosted Vault ConnectionProperties: description: Connection properties for different connection types VaultLocation: type: object discriminator: propertyName: type properties: type: type: string enum: - AWS_SECRET_MANAGER - AZURE_SECRET_MANAGER - GCP_SECRET_MANAGER - MATILLION_CUSTOMER_VAULT - DEFAULT_SECRET_VAULT securitySchemes: bearerAuth: bearerFormat: JWT description: a valid bearer token scheme: bearer type: http ````