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

# How secrets work

> Securely store API keys, tokens, and credentials for your environments and agents.

Secrets securely store and inject sensitive data into your environments - API keys, access tokens, credentials, and certificates that shouldn't be in source code.

Both humans and agents need secrets. When Ona Agent connects to Linear, authenticates with AWS, or uses MCP servers, it pulls credentials from secrets you've configured.

Secrets are configured at three levels: organization, project, or user. They are automatically made available to any environment launched from that project. [Service accounts](/ona/organizations/service-accounts#secrets) can also have secrets attached for use in automations. This ensures consistent and secure access to sensitive data across your development workflow.

## Secret Precedence

When secrets with the same name exist at different levels, they follow a strict precedence order:

1. **User Secrets** - Highest precedence
2. **Project Secrets** - Middle precedence
3. **Organization Secrets** - Lowest precedence

This means:

* User secrets override both project and organization secrets with the same name and mount
* Project secrets override organization secrets with the same name
* Organization secrets have the lowest priority

Learn more about managing [organization secrets](/ona/organizations/organization-secrets), [project secrets](/ona/projects/project-secrets), or [user secrets](/ona/configuration/secrets/user-secrets).

## Encryption of Secrets

All secrets you create are protected with industry-standard encryption. Secrets can only be retrieved by environments created from your projects (for Project secrets) or your user (for User secrets).

We use `AES256-GCM` to encrypt all secrets at rest in the database, with an additional layer of protection through AWS RDS encryption. This dual-layer approach ensures your sensitive data remains secure both at the application level and infrastructure level. In transit, all secrets are encrypted using TLS.

**Ona employees do not have access to the encryption keys and cannot decrypt your secrets.**

## Secrets and environment lifecycle

When you create or update a secret, the change is automatically propagated to all running environments within the secret's scope (organization, project, or user). Propagation can take up to 2 minutes.

* **File secrets** are updated in place at their mount path.
* **Environment variable secrets** are updated on disk, but running processes won't see the new value until the environment is restarted or the Dev Container is rebuilt.
* **Container registry secrets** are updated, and new values are used the next time an image is pulled.

## Using secrets during builds

Organization and project secrets are automatically available during Dev Container image builds via [BuildKit secret mounts](https://docs.docker.com/build/building/secrets/#secret-mounts). No changes to `devcontainer.json` are needed. Your Dockerfile controls which `RUN` steps can access them using `--mount=type=secret`.

For setup instructions and examples, see [Using secrets during builds](/ona/configuration/devcontainer/overview#using-secrets-during-builds).

## Types of secrets

* **[Environment Variables](/ona/configuration/secrets/environment-variables)** - Key-value pairs injected into your environment
* **[Files](/ona/configuration/secrets/files)** - Entire files (certificates, config files) injected into your environment
* **[Container Registry Secrets](/ona/configuration/secrets/container-registry-secret)** - Authentication for private container registries