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

# Credential

> MDX frontmatter reference for credential resources

**Subdirectory:** `credentials/` · **Body:** must be empty

Credentials carry no body - everything is in frontmatter. **Secret values are never exported by `pull`.** When you `sync`, supply the value from your environment via the `${ENV_VAR}` placeholder so secrets stay out of git.

## Frontmatter

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `org` | string \| null | No | tenant | Organization name. Omit (or `null`) for tenant-scoped credentials available to every org. |
| `name` | string | **Yes** | - | Identifier referenced by agents (in `credential_config[].credential`). |
| `type` | `SECRET` \| `VAULT_PATH` | **Yes** | - | `SECRET` stores the encrypted value in 2501; `VAULT_PATH` references an external vault path. |
| `value` | string | When `type=SECRET` | - | The secret itself. Use `${ENV_VAR}` so the value is supplied at sync time and never ends up in git. |
| `vault_path` | string | When `type=VAULT_PATH` | - | The path in your external vault (e.g. `secret/prod/db-password`). |
| `description` | string \| null | No | `null` | Operator-facing note about what this credential is for. |

## Fields NOT supported

* `id`, `tenant_id`, `created_at`, `updated_at` - system-set
* The actual decrypted value on `pull` - intentionally **never exported**
* `is_agent_accessible` - **deprecated**. Agent access is now governed by the per-agent accessible-credentials allowlist, not a per-credential flag. The field is accepted-and-ignored on existing files so older repos still `sync`; you can safely delete it.

## Example: a SECRET credential

```mdx credentials/web-admin-password.mdx theme={null}
---
org: platform-team
name: web-admin-password
type: SECRET
value: ${WEB_ADMIN_PASSWORD}
description: Sudo password for the web tier
---
```

At sync time, `${WEB_ADMIN_PASSWORD}` is resolved from your shell or CI secret store.

## Example: a VAULT\_PATH credential

```mdx credentials/prod-db-password.mdx theme={null}
---
org: platform-team
name: prod-db-password
type: VAULT_PATH
vault_path: secret/data/prod/db
description: Prod DB password - pulled at task time from HashiCorp Vault
---
```

## Gotchas

* **`pull` is a one-way export of metadata only.** Re-running `pull` will *not* fill in `value` - it stays out of git by design.
* **`SECRET` requires `value` at sync time.** If `${WEB_ADMIN_PASSWORD}` is unset in the environment, sync rejects the credential. Pre-existing credentials with a value already on the platform are *not* overwritten by an empty placeholder - sync skips the field rather than wiping it.
* **Body must be empty.** Putting anything in the MDX body fails validation. The value goes in frontmatter only.
* **Tenant scoping matters for provider keys.** A credential referenced by a [Provider](/0.16/configure/providers)'s `API Key Var Name` must be tenant-scoped (`org` unset or `null`).


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