> ## Documentation Index
> Fetch the complete documentation index at: https://helpcenter.magure.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets and Vault

> HashiCorp Vault integration and credential management system for secure secret storage and runtime injection

MagOneAI uses HashiCorp Vault as its central secrets management system. All sensitive credentials — API keys, OAuth tokens, database passwords, and service credentials — are stored in Vault, never in configuration files, environment variables, or application databases.

This architecture ensures that secrets are encrypted, access-controlled, audited, and can be rotated without service disruption.

## HashiCorp Vault integration

Vault provides enterprise-grade secrets management with security guarantees that meet the requirements of regulated industries.

### Why Vault?

<CardGroup cols={2}>
  <Card title="Encryption everywhere" icon="lock">
    Secrets encrypted at rest using AES-256-GCM. Encryption keys are never stored with the encrypted data. Transit encryption for all secret access.
  </Card>

  <Card title="Access control" icon="user-lock">
    Fine-grained policies control which services and users can access which secrets. Deny-by-default security model.
  </Card>

  <Card title="Audit logging" icon="clipboard-list">
    Every secret read, write, and deletion is logged with user, timestamp, and source IP. Tamper-evident audit trail.
  </Card>

  <Card title="Dynamic secrets" icon="arrows-rotate">
    Automatic secret rotation and expiry. OAuth tokens refreshed before expiration. Zero-downtime credential rotation.
  </Card>
</CardGroup>

### Vault architecture in MagOneAI

MagOneAI integrates with Vault at multiple levels:

```
┌─────────────────────────────────────────────────────────┐
│  MagOneAI Platform                                      │
│                                                         │
│  ┌──────────────┐      ┌──────────────┐               │
│  │   Admin      │      │    Studio    │               │
│  │   Portal     │      │              │               │
│  └──────┬───────┘      └──────┬───────┘               │
│         │                      │                        │
│         └──────────┬───────────┘                        │
│                    │                                    │
│         ┌──────────▼───────────┐                        │
│         │  Vault Client        │                        │
│         │  (Application Layer) │                        │
│         └──────────┬───────────┘                        │
│                    │                                    │
│         ┌──────────▼────────────┐                       │
│         │  HashiCorp Vault      │                       │
│         │                       │                       │
│         │  ┌─────────────────┐  │                       │
│         │  │ Platform Secrets│  │                       │
│         │  │ - LLM API Keys  │  │                       │
│         │  │ - Service Creds │  │                       │
│         │  └─────────────────┘  │                       │
│         │                       │                       │
│         │  ┌─────────────────┐  │                       │
│         │  │ User Tokens     │  │                       │
│         │  │ - OAuth Tokens  │  │                       │
│         │  │ - Personal Keys │  │                       │
│         │  └─────────────────┘  │                       │
│         └───────────────────────┘                       │
└─────────────────────────────────────────────────────────┘
```

The application layer accesses Vault using its own Vault token (managed by the platform administrator). Individual services and users never access Vault directly — the application layer handles all secret retrieval and injection.

## The three-tier credential system

MagOneAI manages three distinct types of credentials, each with different lifecycle and access patterns.

### 1. Platform credentials

**What they are:** API keys and service credentials needed by the platform itself to function.

**Examples:**

* OpenAI API keys for GPT-4 access
* Anthropic API keys for Claude access
* Database connection strings
* Email service credentials (SendGrid, Postmark)
* Infrastructure service credentials

**Who manages them:** SuperAdmins via the Admin Portal

**Storage:** Vault paths under `secret/platform/`

**Lifecycle:**

1. SuperAdmin creates a provider in Admin Portal (e.g., "OpenAI Production")
2. SuperAdmin enters the API key or selects a Vault path
3. Platform stores the reference (e.g., `vault:secret/platform/openai/api-key`)
4. When an agent uses GPT-4, the platform retrieves the key from Vault at runtime
5. The key is injected into the API call and never logged or stored

**Rotation:** SuperAdmin updates the key in Vault. The platform uses the new key on the next request. No service restart needed.

### 2. User tokens

**What they are:** OAuth tokens that allow MagOneAI to act on behalf of individual users when calling tools.

**Examples:**

* Google OAuth tokens for Gmail, Calendar, Drive access
* Microsoft OAuth tokens for Outlook, Teams, OneDrive access
* Slack OAuth tokens for sending messages
* GitHub OAuth tokens for repository access

**Who manages them:** Individual users via OAuth consent flows

**Storage:** Vault paths under `secret/users/{user_id}/`

**Lifecycle:**

1. User initiates OAuth flow (e.g., "Connect Google Account" in Studio)
2. User consents to requested scopes in Google's OAuth screen
3. MagOneAI receives access token and refresh token
4. Tokens are stored in Vault at `secret/users/{user_id}/google`
5. When an agent sends an email via Gmail, MagOneAI retrieves the user's token
6. Token is injected into the MCP connection and used to authenticate the Gmail API call

**Rotation:** MagOneAI automatically refreshes tokens before they expire using the refresh token. Users are never aware of this process.

**Revocation:** Users can revoke tokens in Studio settings. Tokens are also automatically revoked when a user is removed from an organization.

### 3. MCP connections

**What they are:** Active tool connections that combine platform credentials and user tokens to enable agent tool use.

**Examples:**

* Gmail connection using a user's OAuth token
* OpenAI connection using a platform API key
* Database connection using platform credentials and user identity

**Who manages them:** Created automatically at runtime by the platform

**Storage:** Not stored — created on-demand when an agent needs to call a tool

**Lifecycle:**

1. Agent execution requires calling a tool (e.g., `gmail_send`)
2. Platform identifies that the tool requires a user OAuth token
3. Platform retrieves the executing user's Google OAuth token from Vault
4. Platform creates an MCP connection with the token injected
5. Tool executes with the credential
6. Connection is closed and credential is not retained

**Security:** Credentials are only in memory during the execution. They are never logged, written to disk, or exposed in agent outputs.

## Secret reference syntax

MagOneAI uses a prefix-based syntax to distinguish between different secret sources. This allows flexibility in deployment while maintaining clear semantics.

### Reference types

<Tabs>
  <Tab title="vault: prefix">
    **Syntax:** `vault:secret/path/to/secret`

    **Usage:** Production deployments

    **Example:** `vault:secret/platform/openai/api-key`

    **Behavior:**

    * Application retrieves the secret from HashiCorp Vault at runtime
    * Requires Vault to be configured and accessible
    * Provides encryption, access control, and audit logging
    * Supports secret rotation without restart

    **Best practice:** Always use `vault:` references in production. This is the secure, auditable, enterprise-grade approach.
  </Tab>

  <Tab title="env: prefix">
    **Syntax:** `env:ENVIRONMENT_VARIABLE_NAME`

    **Usage:** Development and simple deployments

    **Example:** `env:OPENAI_API_KEY`

    **Behavior:**

    * Application reads the value from an environment variable
    * No encryption, access control, or audit logging
    * Secret rotation requires service restart
    * Secret visible to anyone with access to the process environment

    **Best practice:** Only use `env:` for local development or proof-of-concept deployments. Not recommended for production.
  </Tab>

  <Tab title="Plain name">
    **Syntax:** `my-openai-key` (a name or UUID, no prefix)

    **Usage:** A shorthand that still resolves through Vault

    **Behavior:**

    * Resolved by looking the name up in Vault (e.g. under the org's `llm/` path) — it is *not* a literal secret value
    * Provides the same encryption, access control, and audit logging as an explicit `vault:` reference

    **Best practice:** A raw secret value pasted in as-is is **not** accepted — an unrecognized reference format is rejected rather than stored in plaintext. Always keep the actual secret in Vault (or an environment variable) and reference it.
  </Tab>
</Tabs>

### Configuring Vault references

When configuring a provider in the Admin Portal:

<Steps>
  <Step title="Navigate to Providers">
    In Admin Portal, go to Settings → Providers.
  </Step>

  <Step title="Create or edit a provider">
    Click "Add Provider" or edit an existing provider (e.g., OpenAI).
  </Step>

  <Step title="Enter the Vault path">
    In the API Key field, enter the Vault reference: `vault:secret/platform/openai/api-key`
  </Step>

  <Step title="Save the configuration">
    The platform validates that it can access the Vault path and retrieve a value.
  </Step>
</Steps>

The actual API key must already exist in Vault at the specified path. Use the Vault CLI or UI to create the secret:

```bash theme={null}
vault kv put secret/platform/openai api-key="sk-abc123..."
```

## Runtime secret injection

Understanding how secrets flow from Vault to agent executions is crucial for appreciating the security model.

### Example: Agent sends an email via Gmail

Let's trace how credentials flow when an agent sends an email:

<Steps>
  <Step title="Workflow execution starts">
    User triggers a workflow that includes an agent. The agent's instructions include: "Send a summary email to the user via Gmail."
  </Step>

  <Step title="Agent decides to use the gmail_send tool">
    The agent's reasoning determines it needs to send an email. It selects the `gmail_send` tool from its available tools.
  </Step>

  <Step title="Platform identifies required credentials">
    The platform knows that `gmail_send` requires a Google OAuth token scoped to Gmail access.
  </Step>

  <Step title="Platform retrieves user's OAuth token from Vault">
    Using the executing user's ID, the platform fetches `secret/users/{user_id}/google` from Vault.
  </Step>

  <Step title="Platform creates MCP connection">
    An MCP server connection is initialized with the OAuth token injected into the environment. The token is only in memory.
  </Step>

  <Step title="Agent calls the tool">
    The agent invokes `gmail_send` with parameters: recipient, subject, body. The OAuth token is not visible to the agent.
  </Step>

  <Step title="MCP server authenticates with Gmail">
    The MCP server uses the injected OAuth token to authenticate with Google's Gmail API and send the email.
  </Step>

  <Step title="Connection is closed">
    The MCP connection is terminated. The OAuth token is removed from memory. No credential is logged or persisted.
  </Step>
</Steps>

**Key security properties:**

* The OAuth token is retrieved from Vault only when needed
* The token exists in memory only during execution
* The agent never sees or has access to the token
* The token is not logged in execution history or audit logs
* If the token has been revoked, the execution fails immediately (no retry with cached credentials)

### Example: Agent uses OpenAI GPT-4

Let's trace credential flow for an LLM API call:

<Steps>
  <Step title="Agent execution requires LLM inference">
    A workflow activity invokes an agent that uses the GPT-4 model.
  </Step>

  <Step title="Platform identifies the provider">
    The agent configuration specifies `provider: openai` and `model: gpt-4`.
  </Step>

  <Step title="Platform retrieves the provider configuration">
    The application looks up the OpenAI provider configuration, which contains `api_key: vault:secret/platform/openai/api-key`.
  </Step>

  <Step title="Platform retrieves the API key from Vault">
    The application fetches the value at `secret/platform/openai/api-key` from Vault.
  </Step>

  <Step title="Platform makes OpenAI API request">
    The application includes the API key in the `Authorization` header of the HTTPS request to OpenAI's API.
  </Step>

  <Step title="Response is returned">
    OpenAI processes the request and returns the model output. The API key is not logged or stored.
  </Step>
</Steps>

**Key security properties:**

* The API key is retrieved fresh from Vault for each request (with caching for performance)
* If the key in Vault is rotated, the next request uses the new key
* The key is never written to logs, execution history, or audit trails
* The key is transmitted only over TLS-encrypted connections

## Secret rotation

One of Vault's key advantages is enabling secret rotation without service downtime. MagOneAI is designed to support this.

### Rotating platform credentials

To rotate an API key (e.g., OpenAI API key):

<Steps>
  <Step title="Generate a new API key">
    Create a new API key in the provider's portal (e.g., OpenAI's dashboard).
  </Step>

  <Step title="Update the secret in Vault">
    Use the Vault CLI or UI to update the secret:

    ```bash theme={null}
    vault kv put secret/platform/openai api-key="sk-new-key-xyz..."
    ```
  </Step>

  <Step title="Verify the new key works">
    Trigger a test workflow that uses the provider. The platform will retrieve the new key from Vault and use it.
  </Step>

  <Step title="Revoke the old key">
    Once you've verified the new key works, revoke the old key in the provider's portal.
  </Step>
</Steps>

**No service restart required.** The platform retrieves secrets from Vault at runtime, so the new key is used immediately.

### Rotating OAuth tokens

OAuth tokens are rotated automatically by MagOneAI:

1. When the platform retrieves a token, it checks the expiration timestamp
2. If the token expires within the next hour, the platform uses the refresh token to request a new access token
3. The new access token and refresh token are stored in Vault, replacing the old ones
4. The execution proceeds with the fresh token

Users are never aware of this process — tokens are refreshed transparently.

If a refresh token expires or is revoked, the user is prompted to re-authenticate via the OAuth flow.

### Rotation audit trail

All secret accesses are logged by Vault:

* Secret path accessed
* User or service that accessed it
* Timestamp and source IP
* Whether the access was allowed or denied

This creates a complete audit trail for compliance and security investigations.

<Note>
  In production deployments, always use `vault:` references for credentials. The `env:` prefix is provided for development convenience but lacks the security guarantees of Vault — including encryption, access control, audit logging, and zero-downtime rotation.
</Note>

## Vault configuration and deployment

MagOneAI requires a HashiCorp Vault instance to be deployed and accessible. You have several options:

### Self-managed Vault

Deploy your own Vault cluster for maximum control:

* **Advantages:** Full control over encryption keys, audit logs, and access policies. Integrate with existing Vault deployments.
* **Requirements:** Vault 1.11+ running in HA mode (recommended for production). Network connectivity from MagOneAI to Vault.
* **Configuration:** Provide Vault address and authentication token in MagOneAI's environment configuration.

### HashiCorp Cloud Platform (HCP) Vault

Use HashiCorp's managed Vault service:

* **Advantages:** No infrastructure to manage, automatic updates, built-in HA and backups.
* **Requirements:** HCP account and network connectivity to HCP Vault.
* **Configuration:** Provide HCP Vault address and authentication token in MagOneAI's configuration.

### Vault agent for authentication

For production deployments, use Vault Agent to manage authentication:

1. Deploy Vault Agent as a sidecar or on each host
2. Configure Vault Agent with auto-auth (Kubernetes, AWS, Azure, etc.)
3. Vault Agent maintains a fresh Vault token and exposes it to MagOneAI
4. MagOneAI reads the token from a local file (automatically refreshed by Vault Agent)

This eliminates the need to manage long-lived Vault tokens manually.

## Security best practices

<CardGroup cols={2}>
  <Card title="Always use vault: in production" icon="shield-check">
    Never use `env:` prefix or direct secret values in production deployments. Vault provides encryption, access control, and audit logging.
  </Card>

  <Card title="Scope Vault policies narrowly" icon="file-shield">
    Grant MagOneAI only the Vault paths it needs. Use separate policies for platform secrets and user secrets.
  </Card>

  <Card title="Enable Vault audit logging" icon="clipboard-list">
    Configure Vault to log all secret accesses. Integrate these logs with your SIEM for monitoring.
  </Card>

  <Card title="Rotate secrets regularly" icon="arrows-rotate">
    Establish a rotation schedule for platform credentials (e.g., every 90 days). Use automation to reduce manual effort.
  </Card>

  <Card title="Use dynamic secrets where possible" icon="clock-rotate-left">
    For database access, use Vault's dynamic secret engines to generate short-lived credentials instead of static passwords.
  </Card>

  <Card title="Monitor for unauthorized access" icon="triangle-exclamation">
    Alert on Vault access denials or unusual access patterns. Investigate immediately.
  </Card>
</CardGroup>

## Troubleshooting

### "Unable to retrieve secret from Vault"

**Cause:** The platform cannot connect to Vault or the secret path doesn't exist.

**Solutions:**

1. Verify Vault is accessible from the MagOneAI platform (check network connectivity)
2. Verify the secret exists at the specified path using `vault kv get secret/path`
3. Check that the platform's Vault token has permission to read the secret path
4. Review Vault audit logs to see if access was denied

### "OAuth token expired"

**Cause:** The refresh token expired or was revoked, preventing automatic token refresh.

**Solutions:**

1. User must re-authenticate via the OAuth flow in Studio settings
2. After re-authentication, the new token is stored in Vault and the error resolves

### "Secret rotation not taking effect"

**Cause:** Caching may delay the use of the updated secret.

**Solutions:**

1. Wait up to 60 seconds — the platform caches Vault secrets briefly for performance
2. Restart the platform if immediate rotation is critical (though this should not be necessary)

<Warning>
  If you suspect a secret has been compromised, rotate it immediately in Vault and revoke the old value in the provider's portal. Check audit logs for any unauthorized access during the exposure window.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Audit and monitoring" icon="clipboard-list" href="/security/audit-logging">
    Configure comprehensive audit trails and monitoring
  </Card>

  <Card title="Deployment guide" icon="server" href="/platform/infrastructure">
    Deploy MagOneAI with Vault integration
  </Card>
</CardGroup>