> ## Documentation Index > Fetch the complete documentation index at: https://docs.credibledata.com/llms.txt > Use this file to discover all available pages before exploring further. # Create database connection > Creates a new database connection for the specified environment with secure credential storage and connection validation. **Authorization**: Requires environment admin permissions. **Validation**: Tests connection before saving if dryRun is false. **Security**: Credentials are encrypted and stored securely. ## OpenAPI ````yaml /controlplane-public-api-doc.yaml post /organizations/{organizationName}/environments/{environmentName}/connections openapi: 3.1.0 info: title: Credible Admin API description: > The Credible Admin API is a comprehensive REST API that empowers organizations to manage their Malloy data modeling ecosystem with enterprise-grade security and governance. This API provides programmatic access to all administrative functions, enabling seamless integration with existing workflows and automation systems. ## Key Features - **Organization Management**: Create and manage organizations with fine-grained access controls - **Environment & Package Lifecycle**: Full CRUD operations for environments, packages, and versions - **Connection Management**: Secure database connection configuration and management - **Permission Management**: Granular role-based access control (RBAC) at organization, environment, package, workspace, and document levels - **Workspace Management**: Collaborative workspaces for data modeling and analysis - **User & Group Management**: Comprehensive user administration with group-based permissions ## Resource Hierarchy The API follows a hierarchical resource structure with fine-grained permission management at each level: ``` Organizations ├── Permissions ├── Environments │ ├── Permissions │ ├── Packages │ │ ├── Permissions │ │ └── Versions │ └── Connections ├── Workspaces │ ├── Permissions │ └── Documents │ └── Permissions └── Groups ├── Permissions └── Members System-Level Resources: ├── Users ├── System Permissions └── Demo Operations ``` ## Authentication & Authorization All API endpoints require proper authentication. The API implements fine-grained authorization using role-based permissions: - **Admin**: Full access to all resources within scope - **Modeler**: Can create and modify data models and packages - **Viewer**: Read-only access to resources - **Manager**: Workspace management capabilities - **Editor**: Document editing permissions ## Rate Limiting & Best Practices - API requests are rate-limited to ensure system stability - Implement proper error handling and retry logic - Cache responses when appropriate to reduce API calls ## Support & Documentation For additional support, examples, and integration guides, visit our developer documentation or contact our support team. version: v0 contact: name: Credible Support email: support@credibledata.com url: https://credibledata.com/support license: name: Proprietary url: https://credibledata.com/license termsOfService: https://credibledata.com/terms servers: - url: https://{organization}.admin.credibledata.com/api/v0/ description: Production API server variables: organization: default: demo description: Your organization subdomain security: - bearerAuth: [] tags: - name: organizations description: >- Organization management operations for creating, updating, and managing organizational entities - name: organizationPermissions description: >- Fine-grained permission management for organizations, including role assignments and access controls - name: environments description: >- Environment lifecycle management including creation, configuration, and deletion of data modeling environments - name: environmentPermissions description: >- Permission management for environments, controlling access to environment resources and capabilities - name: packages description: >- Package management for Malloy data models, including versioning, publishing, and distribution - name: packagePermissions description: >- Access control for packages, managing who can view, modify, or publish package versions - name: versions description: >- Version management for packages, including archiving, status updates, and lifecycle management - name: connections description: >- Database connection management for secure data source configuration and access - name: materializations description: >- Malloy Persistence materializations (per-version serving anchors for persisted sources) - name: indexes description: >- Malloy Persistence dimensional search indexes (per-version serving anchors for indexed dimensions) - name: runs description: >- Malloy Persistence build/refresh runs — one package-level build event carrying typed units (materialized sources + built indexes) - name: workspaces description: >- Collaborative workspace management for team-based data modeling and analysis - name: workspacePermissions description: >- Access control for workspaces, managing who can view, manage, or collaborate in workspaces - name: documents description: >- Document management within workspaces, including workbooks, dashboards, and other content - name: documentPermissions description: >- Access control for documents, managing who can view, edit, or share document content - name: groups description: >- User group management for organizing users and managing group-based permissions - name: users description: >- User account management including creation, updates, and profile management - name: demo description: Demo and self-service operations for quick setup and testing scenarios - name: permissions description: System-level permission management for administrative functions - name: bookmarks description: >- User bookmark management for saving references to workspaces, models, and chats - name: attributes description: Trusted user attributes for fine-grain (row/column-level) access control - name: invites description: >- Organization-creation invite tokens. A super-admin mints tokens one per call (call `POST /invites` repeatedly to populate an outreach campaign); each token can be redeemed once by an authenticated user to create a new organization on the fly. paths: /organizations/{organizationName}/environments/{environmentName}/connections: post: tags: - connections summary: Create database connection description: > Creates a new database connection for the specified environment with secure credential storage and connection validation. **Authorization**: Requires environment admin permissions. **Validation**: Tests connection before saving if dryRun is false. **Security**: Credentials are encrypted and stored securely. operationId: createConnection parameters: - name: organizationName in: path required: true description: The unique identifier of the organization schema: $ref: '#/components/schemas/IdentifierPattern' - name: environmentName in: path required: true description: The unique identifier of the environment schema: $ref: '#/components/schemas/IdentifierPattern' - name: dryRun in: query required: false description: Whether to test the connection without saving it schema: type: boolean default: false requestBody: content: application/json: schema: $ref: '#/components/schemas/Connection' required: true responses: '200': description: Connection created successfully content: application/json: schema: $ref: '#/components/schemas/Connection' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: schemas: IdentifierPattern: type: string pattern: ^[a-zA-Z0-9_ -]+$ description: Standard identifier pattern for resource names Connection: x-class-name: Connection allOf: - $ref: '#/components/schemas/ConnectionBase' - type: object properties: template: type: string writeOnly: true enum: - bq_demo description: > Create this connection from a managed sample template instead of supplying credentials. The server fills the connection type, configuration, and credentials from the named template (currently only `bq_demo`, our sample BigQuery dataset); any credential or table fields in the request are ignored and the connection name defaults to the template name when omitted. Create-only: never stored or returned. includeTables: type: array nullable: true description: > The list of tables to include, in the format `{dataset/schema}.{table}`. The first part represents the dataset or schema, and the second part is the table name. The second part can be a literal `*` to include all tables. items: $ref: '#/components/schemas/TableNamePattern' type: string example: - sales.orders - finance.* excludeAllTables: type: boolean description: Whether to exclude all tables. default: false excludeTables: type: array nullable: true description: > The list of tables to exclude, in the format `{dataset/schema}.{table}`. The first part represents the dataset or schema, and the second part is the table name. The second part can be a literal `*` to exclude all tables. items: $ref: '#/components/schemas/TableNamePattern' type: string example: - backup.records - temp_data.* indexingStatus: type: string enum: - UNKNOWN - SCHEMA_INDEXING - INDEXED - SKIPPED - FAILED - RETRY - MODEL_SUGGESTION_INDEXING nullable: true description: > Current indexing status of the connection. UNKNOWN means indexing is queued and starts automatically on creation (no manual action; "Start indexing" is an optional re-trigger). SCHEMA_INDEXING means schema indexing is in progress, MODEL_SUGGESTION_INDEXING means schema indexing finished (schema search is usable) and the model-suggestions pipeline is generating dimensions/measures/joins, INDEXED means both pipelines finished, SKIPPED means the connection is excluded from indexing, FAILED means schema indexing failed, RETRY means the connection was updated while indexing was in progress and will be re-indexed when the current job finishes. indexingStatusLastUpdated: type: string format: date-time nullable: true description: ISO 8601 timestamp of when the indexing status was last updated indexingProgress: $ref: '#/components/schemas/ConnectionIndexingProgress' ConnectionBase: type: object description: Database connection configuration and metadata properties: resource: type: string description: Resource path to the connection name: type: string description: Name of the connection type: type: string description: Type of database connection enum: - postgres - bigquery - snowflake - trino - databricks - mysql - duckdb - motherduck - ducklake - publisher fingerprint: type: string description: > Optional, opaque, stable fingerprint of this connection's data identity. It is a hash of the configuration that determines *which data* the connection reaches (its data-locating settings), and deliberately excludes credentials and other secret values, so it stays constant across credential rotation and changes only when the connection is pointed at different data. When present, it is used as this connection's contribution to content-addressed build identifiers so that builds re-address only when the underlying data identity actually changes; consumers should treat it as an opaque token and use the supplied value verbatim rather than deriving their own. This field is optional — when omitted, a connection identity is derived locally instead. attributes: $ref: '#/components/schemas/ConnectionAttributes' proxy: $ref: '#/components/schemas/ConnectionProxy' postgresConnection: $ref: '#/components/schemas/PostgresConnection' bigqueryConnection: $ref: '#/components/schemas/BigqueryConnection' snowflakeConnection: $ref: '#/components/schemas/SnowflakeConnection' trinoConnection: $ref: '#/components/schemas/TrinoConnection' databricksConnection: $ref: '#/components/schemas/DatabricksConnection' mysqlConnection: $ref: '#/components/schemas/MysqlConnection' duckdbConnection: $ref: '#/components/schemas/DuckdbConnection' motherduckConnection: $ref: '#/components/schemas/MotherDuckConnection' ducklakeConnection: $ref: '#/components/schemas/DucklakeConnection' publisherConnection: $ref: '#/components/schemas/PublisherConnection' TableNamePattern: type: string pattern: ^(?:[a-zA-Z0-9_-]+\.)?[a-zA-Z0-9_-]+\.(?:[a-zA-Z0-9_-]+|\*)$ description: >- Table name pattern matching {schema}.{table}, {schema}.*, {catalog}.{schema}.{table}, or {catalog}.{schema}.* ConnectionIndexingProgress: type: object nullable: true description: > Aggregate per-pipeline indexing progress for a connection, polled from the entity-indexing service while the connection is being indexed. Populated on the single-connection read while indexing is in progress (SCHEMA_INDEXING / MODEL_SUGGESTION_INDEXING); null once INDEXED or when progress is unavailable. properties: schemaProgress: $ref: '#/components/schemas/SchemaIndexingProgress' modelSuggestionsProgress: $ref: '#/components/schemas/ModelSuggestionsIndexingProgress' Error: type: object x-model-name: ModelError description: Standard error response format used across all API endpoints properties: code: type: string description: > Machine-readable error code that identifies the specific error condition. Clients should branch on `code`, not on the human-readable `message` — the message text is informational and may change over time. Generic codes (may appear on any endpoint): - `VALIDATION_ERROR`: Request body or path/query parameter failed validation - `AUTHENTICATION_REQUIRED`: Valid authentication is required - `INSUFFICIENT_PERMISSIONS`: User lacks required permissions - `RESOURCE_NOT_FOUND`: Requested resource does not exist - `CONFLICT`: Generic resource state conflict (used when no more specific code applies) - `RATE_LIMIT_EXCEEDED`: API rate limit exceeded - `INTERNAL_ERROR`: Unexpected server error Endpoint-specific codes used by the signup / invites flow: - `ORGANIZATION_NAME_TAKEN`: 409 on `POST /organizations` — the requested org name (URL slug) is already in use. Retry with a different name. - `ORGANIZATION_NAME_RESERVED`: 409 on `POST /organizations` — the requested org name collides with a platform subdomain (e.g. `signup`, `admin`, `data`, `login`) and cannot be claimed. Retry with a different name. - `INVITE_ALREADY_CONSUMED`: 409 on `POST /organizations` — the supplied invite token has already been redeemed into an existing organization. Retry will not help; the token is dead. - `INVITE_ALREADY_CONSUMED_REVOKE`: 409 on `DELETE /invites/{token}` — consumed invites are preserved for audit and cannot be revoked. - `INVITE_INVALID`: 400 on `POST /organizations` — the supplied invite token is malformed or unknown. - `INVITE_EXPIRED`: 400 on `POST /organizations` — the supplied invite token is past its `expiresAt`. - `INVITE_EMAIL_MISMATCH`: 403 on `POST /organizations` — the invite is bound to a different email address than the caller. message: type: string description: Human-readable error message providing details about what went wrong ConnectionAttributes: type: object description: Connection capabilities and configuration attributes properties: dialectName: type: string description: SQL dialect name for the connection isPool: type: boolean description: Whether the connection uses connection pooling canPersist: type: boolean description: Whether the connection supports persistent storage operations canStream: type: boolean description: Whether the connection supports streaming query results ConnectionProxy: type: object description: >- Optional network proxy through which the connection is reached. Applies to any connection type whose database is not directly reachable (e.g. behind a bastion). The proxy is established below the driver, so the driver connects to a local endpoint transparently. Modeled as a discriminated union on `type` so additional proxy mechanisms can be added later. properties: type: type: string description: Proxy mechanism. Currently only SSH local port-forwarding. enum: - ssh ssh: $ref: '#/components/schemas/SshProxyConfig' PostgresConnection: type: object description: PostgreSQL database connection configuration properties: host: type: string description: PostgreSQL server hostname or IP address port: type: integer description: PostgreSQL server port number databaseName: type: string description: Name of the PostgreSQL database userName: type: string description: PostgreSQL username for authentication password: type: string description: PostgreSQL password for authentication connectionString: type: string description: >- Complete PostgreSQL connection string (alternative to individual parameters) sslmode: type: string enum: - disable - no-verify - verify-ca description: >- TLS mode for a connection reached through a `proxy` (SSH bastion). Because the driver connects to a local tunnel endpoint, the cert hostname can't be checked; `verify-ca` validates the server cert chain against the trusted CA bundle (e.g. the baked Amazon RDS roots) without the hostname, `no-verify` encrypts without verifying, and `disable` uses no TLS. The server defaults it to `no-verify` when a proxy is set (so a force-SSL target isn't rejected for plaintext) — a server-applied default, not a schema default. Only valid on a proxied connection — a direct connection uses the deployment PGSSLMODE and rejects this field. BigqueryConnection: type: object description: Google BigQuery database connection configuration properties: defaultProjectId: type: string description: Default BigQuery project ID for queries billingProjectId: type: string description: BigQuery project ID for billing purposes location: type: string description: BigQuery dataset location/region serviceAccountKeyJson: type: string description: JSON string containing Google Cloud service account credentials maximumBytesBilled: type: string description: Maximum bytes to bill for query execution (prevents runaway costs) queryTimeoutMilliseconds: type: string description: Query timeout in milliseconds SnowflakeConnection: type: object description: Snowflake database connection configuration properties: account: type: string description: Snowflake account identifier username: type: string description: Snowflake username for authentication password: type: string description: Snowflake password for authentication privateKey: type: string description: Snowflake private key for authentication privateKeyPass: type: string description: Passphrase for the Snowflake private key warehouse: type: string description: Snowflake warehouse name database: type: string description: Snowflake database name schema: type: string description: Snowflake schema name role: type: string description: Snowflake role name responseTimeoutMilliseconds: type: integer description: Query response timeout in milliseconds TrinoConnection: type: object description: Trino database connection configuration properties: server: type: string description: Trino server hostname or IP address port: type: number description: Trino server port number catalog: type: string description: Trino catalog name schema: type: string description: Trino schema name user: type: string description: Trino username for authentication password: type: string description: Trino password for authentication peakaKey: type: string description: Peaka API key for authentication with Peaka-hosted Trino clusters DatabricksConnection: type: object description: Databricks SQL warehouse connection configuration properties: host: type: string description: >- Databricks workspace host (e.g. dbc-xxxxxxxx-xxxx.cloud.databricks.com) path: type: string description: SQL warehouse HTTP path (e.g. /sql/1.0/warehouses/) token: type: string description: Personal access token for authentication oauthClientId: type: string description: OAuth M2M client ID (service principal) oauthClientSecret: type: string description: OAuth M2M client secret (service principal) defaultCatalog: type: string description: Default Unity Catalog to use for queries defaultSchema: type: string description: Default schema to use for queries setupSQL: type: string description: SQL statements to run when the connection is established MysqlConnection: type: object description: MySQL database connection configuration properties: host: type: string description: MySQL server hostname or IP address port: type: integer description: MySQL server port number database: type: string description: Name of the MySQL database user: type: string description: MySQL username for authentication password: type: string description: MySQL password for authentication DuckdbConnection: type: object description: > DuckDB database connection configuration. Publisher intentionally exposes only data-source intent here. Database files, working directories, filesystem/network policy, extension loading, setup SQL, temp directories, and resource knobs are owned by Publisher so environment configs cannot widen deployment policy through low-level DuckDB settings. properties: attachedDatabases: type: array items: $ref: '#/components/schemas/AttachedDatabase' MotherDuckConnection: type: object description: MotherDuck database connection configuration properties: accessToken: type: string description: MotherDuck access token database: type: string description: MotherDuck database name DucklakeConnection: type: object description: DuckLake lakehouse connection configuration properties: storage: type: object description: Data storage connection configuration (S3 or GCS) properties: bucketUrl: type: string description: >- URL of the storage bucket (e.g. s3://my-bucket/path or gs://my-bucket/path) s3Connection: $ref: '#/components/schemas/S3Connection' description: AWS S3 connection configuration for data storage gcsConnection: $ref: '#/components/schemas/GCSConnection' description: Google Cloud Storage connection configuration for data storage required: - bucketUrl catalog: type: object description: Catalog metadata connection configuration properties: postgresConnection: $ref: '#/components/schemas/PostgresConnection' description: PostgreSQL connection for DuckLake metadata catalog required: - postgresConnection required: - storage - catalog PublisherConnection: type: object description: > Malloy Publisher proxy connection. Proxies SQL to a remote Publisher dataplane instead of connecting to a warehouse directly. The remote dataplane owns authentication, access control, and read-only enforcement. properties: connectionUri: type: string description: > Full URI of the remote connection, e.g. https://org.data.example.com/api/v0/environments//connections/ accessToken: type: string description: Bearer token for the remote dataplane (user-scoped, short-lived) required: - connectionUri SchemaIndexingProgress: type: object description: Connection-schema pipeline progress (tables and columns). properties: tablesTotal: type: integer tablesProcessing: type: integer tablesCompleted: type: integer tablesFailed: type: integer columnsTotal: type: integer nullable: true description: >- Sum of column counts over all tables (null if no counts recorded yet). columnsCompleted: type: integer nullable: true description: Sum of column counts over completed tables. ModelSuggestionsIndexingProgress: type: object description: Connection-model-suggestions pipeline progress. properties: tablesTotal: type: integer tablesProcessing: type: integer tablesCompleted: type: integer tablesFailed: type: integer joinWorkTotal: type: integer nullable: true description: >- Stable denominator for join progress (sum of join-work estimates over planned tables). joinWorkCompleted: type: integer nullable: true description: >- Numerator for join progress (sum of join-work estimates over completed tables). joinsGenerated: type: integer nullable: true dimensionsGenerated: type: integer nullable: true measuresGenerated: type: integer nullable: true SshProxyConfig: type: object description: >- SSH bastion / jump-host config for reaching a database inside a private network via an SSH local port-forward. Authentication is public-key only. properties: host: type: string description: Bastion hostname or IP address (the SSH jump host) port: type: integer default: 22 description: Bastion SSH port (defaults to 22) username: type: string description: SSH username on the bastion privateKey: type: string description: >- PEM-encoded SSH private key used to authenticate to the bastion. Write-only secret (never returned by reads). When updating an existing proxy, leave this blank to keep the stored key. The customer authorizes the matching public key in the bastion's authorized_keys. privateKeyPass: type: string description: >- Passphrase for the encrypted private key, if any. Write-only secret (never returned by reads). When updating, leave blank to keep the stored passphrase (kept only when the private key is also kept, not on rotation). hostKey: type: string description: > Optional pinned bastion host public key(s), as one or more OpenSSH known_hosts lines (or bare base64 blobs), verified on every connect. List multiple lines to pin a load-balanced/HA bastion that presents a different key per backend — any listed key is accepted; a mismatch fails the connection closed. Plain and hashed (`|1|…`) lines both work — only the key blob is compared, never the hostname. When omitted, the tunnel connects without host-key verification (the self-service default); the SSH transport is still encrypted. AttachedDatabase: type: object description: Attached DuckDB database properties: name: type: string pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ example: test_connection, _connection, test_connection_1 type: type: string description: Type of database connection enum: - bigquery - snowflake - postgres - gcs - s3 - azure attributes: $ref: '#/components/schemas/ConnectionAttributes' bigqueryConnection: $ref: '#/components/schemas/BigqueryConnection' snowflakeConnection: $ref: '#/components/schemas/SnowflakeConnection' postgresConnection: $ref: '#/components/schemas/PostgresConnection' gcsConnection: $ref: '#/components/schemas/GCSConnection' s3Connection: $ref: '#/components/schemas/S3Connection' azureConnection: $ref: '#/components/schemas/AzureConnection' S3Connection: type: object description: AWS S3 connection configuration for DuckDB properties: accessKeyId: type: string description: AWS access key ID secretAccessKey: type: string description: AWS secret access key region: type: string description: AWS region (e.g., us-east-1) default: us-east-1 endpoint: type: string description: Custom S3-compatible endpoint URL (optional, for MinIO, etc.) sessionToken: type: string description: AWS session token for temporary credentials (optional) required: - accessKeyId - secretAccessKey GCSConnection: type: object description: Google Cloud Storage connection configuration for DuckDB properties: keyId: type: string description: GCS HMAC access key ID secret: type: string description: GCS HMAC secret key required: - keyId - secret AzureConnection: type: object description: > Azure Data Lake Storage (ADLS Gen2) / Blob Storage connection configuration Supports https://, http://, abfss://, and az:// URL schemes. properties: authType: type: string enum: - service_principal - sas_token description: Authentication method for Azure Storage sasUrl: type: string description: > Full SAS URL including token; required for sas_token auth. Supports single file, directory glob (*.ext), or recursive (**) patterns. Example: https://account.blob.core.windows.net/container/path/*.parquet?sp=rl&st=... tenantId: type: string description: Azure AD tenant ID (required for service_principal) clientId: type: string description: Azure AD application (client) ID (required for service_principal) clientSecret: type: string description: Azure AD client secret (required for service_principal) accountName: type: string description: Azure Storage account name (required for service_principal) fileUrl: type: string description: > Azure file URL to query; required for service_principal auth. Supports single file, directory glob (*.ext), or recursive (**) patterns. Example: https://account.blob.core.windows.net/container/path/** required: - authType responses: BadRequest: description: >- The request was malformed or can not be performed given the state of the system. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- Can not perform the operation due to insufficient permissions or the state of the system. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The specified resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````