Skip to main content
An external connection is a named, reusable declaration of one external system, made when Gateway starts. Interceptors and topic views then reference it by name, instead of each carrying its own copy of the address and credentials.
Preview functionality. This is a preview feature and is subject to change. Inline configuration remains fully supported.
For topic views this is the only way to configure a schema registry. For Interceptors, prefer an external connection when several resources use the same registry: the address and credentials live in one place instead of being repeated in every Interceptor, so rotating a credential or moving a registry is a single edit. Inline configuration keeps working and is not deprecated.

​
Declare a connection

Declare each connection with environment variables that follow this pattern:
<NAME> is a label you choose, and is how a resource references the connection. <PROPERTY> is one of the properties the connection’s type accepts.
Connection names have to start with a letter and can contain letters, numbers and underscores, so DEFAULT_SR is a valid name. A name can’t contain _CONFIG_, because that’s the delimiter between the name and the property. Gateway rejects such a variable at startup rather than guessing where the name ends. Names are case-insensitive and Gateway stores them in upper case, so default_sr and DEFAULT_SR are the same connection. We recommend you declare them in upper case to match the variable.
Every connection needs a TYPE, which selects the system it connects to: Every connection follows the same shape. This one is a Confluent-like schema registry named DEFAULT_SR, which needs only a URL:
Gateway rejects an unrecognized property at startup, naming the variable and listing the properties the connection’s type accepts, so a typo never becomes a silently ignored setting.

​
Reference a connection

A resource reaches a connection through a field in its own configuration: Set the field to the connection’s <NAME>. The schema registry connection declared above is named DEFAULT_SR, so an Interceptor or topic view reaches it with:
Gateway checks the name when you create or update the resource, and rejects an unknown one with 400 Bad Request. Remove a connection that a resource already names and the resource stays saved and visible through the API, but stops serving traffic. An Interceptor can name a schema registry connection, or configure a registry inline in its own schemaRegistryConfig. Gateway rejects a configuration that sets both rather than silently picking one.

​
Connect to a schema registry

Gateway needs a schema registry to decode Avro, Protobuf and JSON-Schema records. Both Interceptors and topic views can reference a schema registry connection. Gateway contacts the registry at startup and fails to start if it can’t be reached — see what happens at startup for the timeout, the permissions the connection needs and what the log shows.

​
Confluent-like schema registries

Set TYPE to CONFLUENT_SCHEMA_REGISTRY for Confluent Schema Registry and compatible registries, including Redpanda Schema Registry:
For every property this type accepts, see the environment variables reference. To reach a registry that needs authentication, pass the registry client’s own properties as additional client properties.
Don’t put credentials in SCHEMA_REGISTRY_URL. Gateway rejects a URL carrying user information before an @ and names the connection, so pass them as additional client properties instead.

​
AWS Glue schema registries

Set TYPE to AWS_SCHEMA_REGISTRY for AWS Glue Schema Registry:
For every property this type accepts, see the environment variables reference. Leave every BASIC_CREDENTIALS_ property unset and Gateway falls back to the AWS SDK’s default credentials provider, which searches environment variables, Java system properties, the shared credentials and config files, and container or instance IAM roles. See how the AWS SDK resolves default credentials.

​
Pass additional client properties

A schema registry connection also accepts any property its registry’s own client understands. Gateway doesn’t interpret these properties. It collects them and hands the map to the client, so a key the client doesn’t recognize passes startup rather than failing it. Use indexed entries, where each value is a key=value pair split at the first =:
Or pass a JSON object, which suits keys containing = and migration from existing JSON configuration:
Both formats work together, under two rules:
  • Indexed entries win. An indexed entry overrides the same key in the JSON object, so you can patch one value without rewriting the object.
  • Two indexed entries can’t share a key. There’s no patch order between them, so Gateway rejects the pair and names the key.
A client property can address the same setting as a typed one — _CONFIG_0=schema.registry.url=… beside _CONFIG_SCHEMA_REGISTRY_URL, for example. Gateway doesn’t check for the overlap, and which of the two it connects with is left to the registry’s client. Which keys to use depends on the registry:

​
Connect to a KMS

Gateway encrypts data in Kafka records with keys held in a key management service. An external connection holds the provider’s address, credentials and account details, so an Interceptor names a key rather than a full key URI. Not every provider is available as an external connection yet. Encryption Interceptors reach more of them through their own inline kmsConfig, so configure a provider inline until it arrives here.

​
HashiCorp Vault

Set TYPE to HASHICORP_VAULT. This example authenticates with a token, one of three auth methods covered below:
For every property a Vault connection accepts, including mutual TLS and connection retry, see the environment variables reference. An external connection reaches less of Vault than inline kmsConfig does. We’re widening it in future releases, and until then inline configuration is the way to use anything missing here:
Don’t put credentials in URI. Gateway rejects a URI carrying user information before an @ and names the connection, so authenticate with AUTH_TYPE and its credentials instead.

​
Authenticate with a token

Set AUTH_TYPE to TOKEN and AUTH_TOKEN to the Vault token Gateway authenticates with:
For every property this method accepts, see the environment variables reference.
Gateway doesn’t renew a token you supply — with AUTH_TYPE set to TOKEN it never calls Vault’s renew endpoint, so the token stays in use until its TTL expires, and recovering means replacing the variable and restarting. AppRole and username/password avoid that: Vault issues a short-lived token and Gateway renews it in the background. If you do use a token, give it a TTL that outlives your deployment window, or keep it fresh outside Gateway. See Vault’s production hardening guidance .

​
Authenticate with AppRole

Set AUTH_TYPE to APP_ROLE and pass the role ID and secret ID. Vault exchanges them for a short-lived token, which Gateway renews in the background:
For every property this method accepts, including AUTH_MOUNT when you mounted it somewhere other than approle, see the environment variables reference.

​
Authenticate with a username and password

Set AUTH_TYPE to USERNAME_PASSWORD and pass the userpass login. Vault exchanges it for a short-lived token, which Gateway renews in the background:
For every property this method accepts, including AUTH_MOUNT when you mounted it somewhere other than userpass, see the environment variables reference.

​
AWS KMS

Set TYPE to AWS_KMS. A connection covers one AWS account in one region. This example authenticates with access keys, one of three credential types covered below:
For every property an AWS KMS connection accepts, see the environment variables reference. REGION and ACCOUNT_ID are both required, because Gateway builds each key’s full ARN from them — so an Interceptor names a key as a bare key id or alias/<name>, never an ARN. See how the ARN is built and what’s rejected. The connection needs kms:Encrypt and kms:Decrypt on every key it uses, allowed by the key policy and by the identity’s IAM policy.

​
Authenticate with access keys

Set CREDENTIALS_TYPE to BASIC and pass a long-lived access key pair:
For every property this type accepts, see the environment variables reference.

​
Authenticate with temporary credentials

Set CREDENTIALS_TYPE to SESSION and pass the session token alongside the key pair. Gateway doesn’t refresh these, so they stop working when they expire:
For every property this type accepts, see the environment variables reference.

​
Authenticate with the AWS default provider chain

Set CREDENTIALS_TYPE to DEFAULT and pass no credentials at all. Gateway uses the AWS SDK’s default provider chain, which searches the container or instance role, IAM Roles for Service Accounts, the shared credentials file and the AWS_ environment variables. This suits a Gateway that already runs with an AWS identity, and it’s the only type where the credentials rotate without a restart:
See how the AWS SDK resolves default credentials .

​
What happens at startup

Connections are read once, when Gateway starts, and this is true of every connection type:
  • Configuration is validated. An unrecognized property, or a malformed value such as a JSON object of additional client properties, fails startup and names the variable.
  • Connections load before persisted resources. Interceptors and topic views are activated from storage after the connections exist, so their names resolve.
  • A missing connection doesn’t stop Gateway. If an Interceptor or topic view names a connection that’s no longer declared, that resource stays saved and visible through the API but doesn’t activate, while everything else starts normally. Gateway logs an error naming the missing connection — check the startup log.
  • Secrets are masked in the startup log. Additional client property values are masked whichever format set them, and their keys stay visible.
Whether Gateway also contacts the external system at startup depends on the connection type: Gateway checks schema registry connections in parallel and waits for all of them to finish, so one broken connection doesn’t hide another — you see every failure in one startup attempt. Each attempt is bounded by GATEWAY_EXTERNAL_CONNECTIONS_INIT_TIMEOUT_SECONDS, which defaults to 30 seconds and caps at 300. See the variable reference. The check, and the permission it needs, differ by registry:
  • Confluent-like — Gateway lists the registry’s subjects, so the connection needs permission to list them even if your Interceptors only read schemas by ID.
  • AWS Glue — Gateway requests a schema version that deliberately doesn’t exist, so the connection needs glue:GetSchemaVersion and a not-found answer counts as success.
A KMS connection is established when an Interceptor that names it loads, so a wrong token or an unreachable Vault server surfaces then rather than at boot, and Gateway starts normally either way. Check the Interceptor’s own status after deploying it, not the startup log.

​
Verify the configuration

Gateway logs each schema registry connection’s startup check. Look for one line per connection:
A failure names the connection and the cause, and Gateway then reports how many failed before it stops:
These lines cover schema registry connections only, since those are the ones Gateway contacts. With none declared — including when you’ve declared only KMS connections — Gateway logs No external connections configured and starts normally. Gateway reports KMS connections separately, one line each:
With none declared, that becomes No KMS connections configured. Neither summary includes a credential.

​
Current limitations

  • Connections are read and checked once, at startup. Changing one takes a restart. Gateway doesn’t monitor a system that becomes unreachable afterwards, so that failure surfaces on traffic needing an uncached schema.
  • A schema-backed topic view has to use SELECT *. A WHERE clause is still allowed. See read schema-encoded topics.
  • Gateway doesn’t contact a KMS at startup. It validates the connection’s properties, so a wrong credential or an unreachable provider surfaces when an Interceptor that names it loads, not at boot.
  • An Interceptor that names a removed connection stops applying, rather than failing. It stays saved and visible through the API, but after a restart the traffic it covered passes through unprocessed. An upcoming release will reject that traffic instead.
  • There’s no API that lists configured connections. Use the startup log to confirm what Gateway loaded.