> ## 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.

# Secrets and connections overview

export const m_runner = "Maia runner";

This guide provides additional clarification on the relationship between [secrets](/docs/guides/secrets-and-secret-definitions) and connections (which include types such as secret definitions, [OAuths connections](/docs/guides/oauth), and [cloud credentials](/docs/guides/cloud-credentials)).

***

## How secrets and connections are related

Sensitive information always lives as a secret in a vault. You can choose:

* A vault hosted by Matillion, currently available in a [Full SaaS project](/docs/guides/secrets-and-secret-definitions#create-a-secret-definition-matillion-full-saas).
* Your own vault in AWS, Google Cloud, or Azure, if you'd rather keep everything inside your own cloud. Currently available when using a [Hybrid SaaS project](/docs/guides/secrets-and-secret-definitions#create-a-secret-definition-hybrid-saas).

A connection contains a reference to a secret. The sensitive value sits in the vault, never inside the connection. That has a useful consequence: the same secret could be reused across many connections and projects, so you don't need to duplicate credentials.

The {m_runner} is the security boundary that controls which secrets can be accessed at any time. Its permissions determine which vaults and secrets are visible and usable. In AWS, for example, this can be enforced through an IAM policy.

***

## Creating a connection and secret in the UI

To streamline administration of connections, you can create and edit secrets and connections in a single step. However, because secrets could be shared across projects and environments, Matillion has added two safeguards to prevent unintended access or mutation within these flows:

* New secrets get a unique name so they can't clash or be accidentally shared. The name is constructed from:

  * The project ID.
  * The environment.
  * The connection name.
  * A random UUID.

  So a secret created as part of managing a connection follows this format:

  `<projectId>-<environment>-<connection name>-<random UUID>`

* Editing sensitive information used in a connection creates a new secret. When the information stored in a secret needs to be changed, Matillion can't guarantee the existing secret isn't used by another project or environment that you don't have permission to edit. This means that rather than mutating the existing secret, the platform creates a fresh one. This incurs a small overhead, given the extra secret in the vault, but the priority is that no one ever gets unintended access to, or accidentally changes, a secret that could have an impact beyond the scope of their permissions.

<Note>
  Longer term, Matillion plans to add flexibility, for example selecting an existing secret instead of always creating a new one.
</Note>

***

## Creating a connection via the public API

The creation of secrets and connections in the [public API](/docs/api-reference/maia-api-overview) follows the underlying decoupled model and requires two steps to create:

1. Create the secret in the vault.
2. Create the connection, pointing at that secret.