C3 AI Documentation Home

Custom Connector Credentials

Custom connectors use the VirtualSourceSystem credential model to store and retrieve the information required to authenticate with external systems.

Credentials are associated with a connector instance and maintained separately from the connector implementation. This allows multiple connector instances based on the same implementation to use different credentials.

Credential Types

Define connector-specific credentials by creating a subtype of VirtualSourceSystem.Credentials.

Type
type MyConnector.Credentials mixes VirtualSourceSystem.Credentials {
    name: string
    endpoint: string
    @config(secret=true)
    authToken: string

    forName: ~ js-server
}

The credential type can contain values required to communicate with the external system, such as endpoints, account identifiers, authentication tokens, or other connector-specific properties. Because VirtualSourceSystem.Credentials mixes Named, a concrete credential type must also implement forName. The name field itself is already inherited from Named; the example above redeclares it only to show the complete set of properties an instance needs, not because the field must be redeclared.

Each credential has a name that identifies it within the connector instance's credential store. A connector instance can maintain multiple named credential entries such as separate entries for live-query and Data Integration access, or one per account.

Secret Storage

Mark sensitive credential fields with @config(secret=true).

Type
@config(secret=true)
authToken: string

Secret fields are stored using the platform's secret-handling mechanism. When credentials are retrieved without requesting secret values, secret fields are masked rather than returned in clear text.

Connector implementations should treat secret values as sensitive data and avoid exposing them through logs, error messages, or other output.

Associate Credentials with a Connector Instance

Use setCredentials(credentials, merge) to associate credentials with a registered connector instance. Credentials are keyed by their name property.

JavaScript
connector.setCredentials(
    MyConnector.Credentials.make({
        name: "default",
        endpoint: "https://api.example.com",
        authToken: "..."
    }),
    false
);

When merge is false, an existing credential entry with the same name is replaced. When merge is true, the supplied fields are merged into the existing entry, and fields that are not provided remain unchanged.

In either mode, if no credential entry with the specified name exists, a new entry is created.

Retrieve Credentials

Use getCredentialsByKey(key, secrets) to retrieve a named credential entry. The key identifies the credential entry. The secrets argument determines whether secret values are requested.

To retrieve credentials without exposing secret values:

JavaScript
connector.getCredentialsByKey(key, false);

Secret fields are masked on this retrieval path.

When secret values are required to communicate with the external system:

JavaScript
connector.getCredentialsByKey(key, true);

Pass true for secrets to return secret field values. setCredentials stores these credentials in the application configuration. You can read them when your role allows you to call getCredentialsByKey.

If no credential entry exists for the specified key, getCredentialsByKey returns null.

Remove Credentials

Use removeCredentialsByKey(key) to remove a named credential entry from a connector instance.

JavaScript
connector.removeCredentialsByKey(key);

If the specified credential entry does not exist, the operation has no effect. Removing credentials from one connector instance does not affect credentials associated with other connector instances.

Credential Storage

Credential entries are stored in the connector configuration's virtualCredentials map, keyed by credential name.

Access credentials through the key-based APIs (setCredentials, getCredentialsByKey, and removeCredentialsByKey) rather than reading the configuration directly. Secret fields in the configuration remain subject to the platform's secret-handling behavior.

Runtime Credential Resolution

Credential resolution is scoped to the connector instance. Application types, VirtualSourceCollection instances, and VirtualTargetCollection instances reference a registered VirtualSourceSystem. The connector then resolves the credentials associated with its instance when communicating with the external system.

This separation allows multiple connector instances based on the same implementation to use different credentials.

Credentials and Package Metadata

Connector instances can be provisioned as application package metadata while credentials are configured separately for the deployed connector instance.

This separation allows an application package to define the connector instance without embedding environment-specific secret values in the connector definition.

For information about declaratively provisioning connector instances, see Implement a Custom Connector.

Credential API Considerations

Custom connectors use the key-based credential APIs described in this topic.

Legacy credential methods inherited from the SourceSystem contract — credentials, credentialsWithSecrets, credentialsWithMaskedSecrets, and removeCredentials — throw a not-implemented error on a VirtualSourceSystem connector, because they assume a single credential set rather than the multi-entry, name-keyed model custom connectors use. Use setCredentials, getCredentialsByKey, and removeCredentialsByKey instead.

Was this page helpful?