Skip to main content
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?

Encryption everywhere

Secrets encrypted at rest using AES-256-GCM. Encryption keys are never stored with the encrypted data. Transit encryption for all secret access.

Access control

Fine-grained policies control which services and users can access which secrets. Deny-by-default security model.

Audit logging

Every secret read, write, and deletion is logged with user, timestamp, and source IP. Tamper-evident audit trail.

Dynamic secrets

Automatic secret rotation and expiry. OAuth tokens refreshed before expiration. Zero-downtime credential rotation.

​
Vault architecture in MagOneAI

MagOneAI integrates with Vault at multiple levels:
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

Syntax: vault:secret/path/to/secretUsage: Production deploymentsExample: vault:secret/platform/openai/api-keyBehavior:
  • 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.

​
Configuring Vault references

When configuring a provider in the Admin Portal:
1

Navigate to Providers

In Admin Portal, go to Settings → Providers.
2

Create or edit a provider

Click “Add Provider” or edit an existing provider (e.g., OpenAI).
3

Enter the Vault path

In the API Key field, enter the Vault reference: vault:secret/platform/openai/api-key
4

Save the configuration

The platform validates that it can access the Vault path and retrieve a value.
The actual API key must already exist in Vault at the specified path. Use the Vault CLI or UI to create the secret:

​
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:
1

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.”
2

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

Platform identifies required credentials

The platform knows that gmail_send requires a Google OAuth token scoped to Gmail access.
4

Platform retrieves user's OAuth token from Vault

Using the executing user’s ID, the platform fetches secret/users/{user_id}/google from Vault.
5

Platform creates MCP connection

An MCP server connection is initialized with the OAuth token injected into the environment. The token is only in memory.
6

Agent calls the tool

The agent invokes gmail_send with parameters: recipient, subject, body. The OAuth token is not visible to the agent.
7

MCP server authenticates with Gmail

The MCP server uses the injected OAuth token to authenticate with Google’s Gmail API and send the email.
8

Connection is closed

The MCP connection is terminated. The OAuth token is removed from memory. No credential is logged or persisted.
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:
1

Agent execution requires LLM inference

A workflow activity invokes an agent that uses the GPT-4 model.
2

Platform identifies the provider

The agent configuration specifies provider: openai and model: gpt-4.
3

Platform retrieves the provider configuration

The application looks up the OpenAI provider configuration, which contains api_key: vault:secret/platform/openai/api-key.
4

Platform retrieves the API key from Vault

The application fetches the value at secret/platform/openai/api-key from Vault.
5

Platform makes OpenAI API request

The application includes the API key in the Authorization header of the HTTPS request to OpenAI’s API.
6

Response is returned

OpenAI processes the request and returns the model output. The API key is not logged or stored.
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):
1

Generate a new API key

Create a new API key in the provider’s portal (e.g., OpenAI’s dashboard).
2

Update the secret in Vault

Use the Vault CLI or UI to update the secret:
3

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

Revoke the old key

Once you’ve verified the new key works, revoke the old key in the provider’s portal.
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.
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.

​
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

Always use vault: in production

Never use env: prefix or direct secret values in production deployments. Vault provides encryption, access control, and audit logging.

Scope Vault policies narrowly

Grant MagOneAI only the Vault paths it needs. Use separate policies for platform secrets and user secrets.

Enable Vault audit logging

Configure Vault to log all secret accesses. Integrate these logs with your SIEM for monitoring.

Rotate secrets regularly

Establish a rotation schedule for platform credentials (e.g., every 90 days). Use automation to reduce manual effort.

Use dynamic secrets where possible

For database access, use Vault’s dynamic secret engines to generate short-lived credentials instead of static passwords.

Monitor for unauthorized access

Alert on Vault access denials or unusual access patterns. Investigate immediately.

​
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)
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.

​
Next steps

Audit and monitoring

Configure comprehensive audit trails and monitoring

Deployment guide

Deploy MagOneAI with Vault integration