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

# Secrets

> Store credentials securely, rotate their values, and share them with projects

A **secret** stores a credential such as a model API key, machine environment value, MCP token, or integration credential. Other resources reference the secret by its `sec_…` ID instead of storing the value themselves.

Secret values are encrypted and never returned by read endpoints. Rotating a secret updates the value used by its existing references, so nothing needs to be redeployed.

## Kinds and owners

You can create these kinds:

| `kind` | Holds | Created by |
| - | - | - |
| `generic` | One value, such as an API key, token, or password | You |
| `oauth_token_set` | Access/refresh tokens with refresh metadata | The [MCP OAuth flow](/tools/mcp#connect-with-oauth), or you |
| `aws_credentials` | AWS access credentials, with an optional session token or role to assume | You |
| `github_app_credentials` | GitHub App ID, RSA private key and webhook secret | You; see [GitHub setup](/integrations/github#connect-your-github-app) |

Every secret has exactly one owner. A project can use a secret only if the project owns it or holds an explicit [grant](#grant-a-secret-to-a-project) — org and user ownership don't make a secret visible to projects on their own:

| Owner | Typical use |
| - | - |
| `{ "kind": "org" }` | Org-level resources — [model provider](/organization/model-providers) credentials, [machine pool](/machines/pools) API keys. Grant it to projects that need it directly. |
| `{ "kind": "project", "project_id": … }` | That project's agent configs and machines |
| `{ "kind": "user" }` | Personal credentials; grant to the projects that need them |

The convention that keeps orgs tidy: own each secret at the narrowest scope that needs it. A model key the whole org shares is org-owned; one project's GitHub deploy token is project-owned.

## Create a secret

**API**

The examples assume the client, `$ORG`/`orgID`, and `$PROJ`/`projectID` setup from the [quickstart](/quickstart).

```bash CLI theme={null}
npx omnara secrets create \
  --owner-kind project \
  --owner-project-id proj_7mv4qtrwz3jehcyd5n6a2bfgik \
  --name github-deploy-token \
  --metadata '{"rotates": "quarterly"}' \
  --material-kind generic \
  --material-value "ghp_..." \
  --json
```

```bash REST theme={null}
curl "$OMNARA_API/orgs/$ORG/secrets" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": { "kind": "project", "project_id": "'"$PROJ"'" },
    "name": "github-deploy-token",
    "metadata": { "rotates": "quarterly" },
    "material": { "kind": "generic", "value": "ghp_..." }
  }'
```

```typescript SDK theme={null}
const secret = await sdk.createSecret({
  client,
  path: { orgID },
  body: {
    owner: { kind: 'project', project_id: projectID },
    name: 'github-deploy-token',
    metadata: { rotates: 'quarterly' },
    material: { kind: 'generic', value: 'ghp_...' },
  },
})
```

```json theme={null}
{
  "id": "sec_7jehcyd5n6a2bfgik7mv4qtrwz",
  "owner": { "kind": "project", "project_id": "proj_7mv4qtrwz3jehcyd5n6a2bfgik" },
  "name": "github-deploy-token",
  "kind": "generic",
  "current_version_number": 1,
  "...": "..."
}
```

For MCP OAuth, use the built-in [OAuth flow](/tools/mcp#connect-with-oauth) — `npx omnara secrets mcp-oauth` runs it end to end from the terminal. If you need to import OAuth tokens yourself, see the [secret schema](/api-reference/endpoints/secrets/create-secret).

**Dashboard**

With **All projects** selected in the project switcher, open **Secrets** and pick the **User** or **Organization** tab; for a project secret, open **Secrets** inside the project. Click **New secret**, name it, and choose **Generic**, **OAuth token set**, **MCP OAuth secret**, or **AWS credentials**. For MCP OAuth, click **Authorize and Create Secret** to run the [OAuth flow](/tools/mcp#connect-with-oauth). You can also pick projects under **Share with** in the same dialog.

On both surfaces, reads return the secret's metadata, never its value. If you lose the value, rotate the secret.

## Rotate a secret

Rotation creates a new version while keeping the same secret ID. The CLI shows the current version but cannot rotate it.

```bash REST theme={null}
curl "$OMNARA_API/orgs/$ORG/secrets/sec_7jehcyd5n6a2bfgik7mv4qtrwz/versions" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"material": {"kind": "generic", "value": "ghp_new..."}}'
```

```typescript SDK theme={null}
const rotated = await sdk.createSecretVersion({
  client,
  path: { orgID, secretID: 'sec_7jehcyd5n6a2bfgik7mv4qtrwz' },
  body: { material: { kind: 'generic', value: 'ghp_new...' } },
})
```

The response has `current_version_number: 2`. Existing references use the new current value without changing their `sec_…` ID. Processes already running keep the environment they started with.

## Manage secrets

Use the secrets pages or API to search for secrets. **Edit** can change a secret's name and value; the API also supports metadata updates.

You cannot delete a secret while a model provider, machine pool, or integration uses it as its credential. Replace the secret on that resource — or delete the resource — first.

## Grant a secret to a project

A grant lets a project use a secret it does not own.

**API**

```bash CLI theme={null}
npx omnara grant secrets add sec_7jehcyd5n6a2bfgik7mv4qtrwz \
  --target-project-id proj_4qtrwz3jehcyd5n6a2bfgik7mv \
  --json
```

```bash REST theme={null}
curl "$OMNARA_API/orgs/$ORG/secrets/sec_7jehcyd5n6a2bfgik7mv4qtrwz/grants" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_project_id": "proj_4qtrwz3jehcyd5n6a2bfgik7mv"}'
```

```typescript SDK theme={null}
const grant = await sdk.createSecretGrant({
  client,
  path: { orgID, secretID: 'sec_7jehcyd5n6a2bfgik7mv4qtrwz' },
  body: { target_project_id: 'proj_4qtrwz3jehcyd5n6a2bfgik7mv' },
})
```

```json theme={null}
{
  "id": "sgr_yd5n6a2bfgik7mv4qtrwz3jehc",
  "secret_id": "sec_7jehcyd5n6a2bfgik7mv4qtrwz",
  "target_project_id": "proj_4qtrwz3jehcyd5n6a2bfgik7mv",
  "...": "..."
}
```

To review a secret's project grants, use `npx omnara grant secrets list {secret-id}`, `GET /orgs/$ORG/secrets/{secret-id}/grants`, or `sdk.listSecretGrants`. To remove one, use `npx omnara grant secrets delete {secret-id} {grant-id}`, `DELETE` on the grant, or `sdk.deleteSecretGrant`.

To list every secret a project can use (no CLI command for this yet):

```bash REST theme={null}
curl "$OMNARA_API/orgs/$ORG/projects/$PROJ/secrets" -H "Authorization: Bearer $OMNARA_TOKEN"
```

```typescript SDK theme={null}
const available = await sdk.listProjectAvailableSecrets({
  client,
  path: { orgID, projectID },
})
```

This includes secrets owned by the project and secrets explicitly granted to it. `availability.source` is `direct` for project-owned secrets and `grant` for granted secrets.

**Dashboard**

On the secret's row, click **Share with project** and pick the target project (or pick projects under **Share with** while creating the secret). To view or revoke a project's shared secrets, open the project's **Secrets** page and select the **Shared** tab. Click **Stop sharing secret** to remove access without deleting the secret.

## Where secret IDs are used

These fields reference a secret instead of storing its value directly:

| Surface | Field |
| - | - |
| [Model provider config](/organization/model-providers) | `credential_secret_id`, `secret_headers` |
| [Machine](/machines/connect) environment | `secret_env` |
| [Pool](/machines/pools) environment | `default_machine_secret_env`; project-specific pool grants can add or override values with `default_machine_secret_env_overlay` |
| Agent config [machine sources](/agents/configuration#machines) | `secret_env_overlay` |
| Agent config [MCP auth](/tools/mcp) | `auth.secret_id` |
| [Machine pool](/machines/pools) provider | `provider_auth_secret_id` |

> [!NOTE]
>
> Full schema and playground: [Create secret](/api-reference/endpoints/secrets/create-secret) · [Create secret version](/api-reference/endpoints/secrets/create-secret-version) · [Secret grants](/api-reference/endpoints/secrets/create-secret-grant) · [Project secrets](/api-reference/endpoints/secrets/list-secrets-available-to-project).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.