Secrets and Vault

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?

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-5 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-5, 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 Calendar access
• Microsoft OAuth tokens for Outlook mail and calendar 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 Microsoft Account" in Studio)
2. User consents to requested scopes on Microsoft's OAuth screen
3. MagOneAI receives access token and refresh token
4. Tokens are stored in Vault at secret/users/{user_id}/microsoft
5. When an agent sends an email via Outlook, MagOneAI retrieves the user's token
6. Token is injected into the MCP connection and used to authenticate the Microsoft Graph 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:

• Outlook Email 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., send_email)
2. Platform identifies that the tool requires a user OAuth token
3. Platform retrieves the executing user's Microsoft 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.

How a credential is chosen: user, then project, then org

A tool can have credentials configured at more than one level, so the platform needs a rule for which one wins. It walks the scopes in order and takes the first match:

1. User: a credential the executing user connected themselves. Always tried first, and needs no permission check, because it is their own.
2. Project: a credential shared with the project. Requires that the user is a member of that project.
3. Organization: the org-wide credential. Requires that the user is a member of the org.

The first level that has a credential wins, and the search stops there. If none do, the tool call fails with a "no credentials configured" error rather than running unauthenticated.

This is what makes the shared-then-personal pattern work. An organization can connect one service account so everything runs out of the box, and any individual who connects their own account transparently overrides it for their own runs, with no configuration change to the workflow.

Managed secrets

The three tiers above are credentials MagOneAI manages for you. Managed secrets are the ones you add yourself: store a token once, give it a name, and reference it by that name from any node.

Only metadata lives in the database: the name, the key, the scope, a version number and an optional expiry. The value itself exists in Vault and nowhere else. No API route returns a secret's value, masked or otherwise.

Scopes

A secret is stored at one of three scopes, and who may create one differs per scope:

Referencing a secret

{{secret:stripe-api-key}}

Resolution looks at the narrowest scope first: your own secrets, then the project's, then the organization's. That means a user-scoped secret with the same key shadows the project's, which is what lets one person test with their own credential without changing the workflow.

A key must be lowercase, with letters, digits, dashes or underscores. A value may be up to 64 KB.

Expiry

A secret can carry an expiry date, which drives a warning in the product.

Rotating a secret replaces its value and bumps its version, so a consumer can tell the value changed. The replacement's expiry is taken from the rotation itself: if you omit one, any previous expiry is cleared rather than carried over onto a value it never described.

Why creating a secret verifies the organization for you

When you create a secret, MagOneAI derives the organization from the scope rather than trusting what the request claimed.

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

Configuring Vault references

When configuring a provider in the Admin Portal:

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

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 Outlook

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

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-5

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

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):

vault kv put secret/platform/openai api-key="sk-new-key-xyz..."

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.

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

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)

Next steps