> ## 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 lands 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.8/configure/providers)'s `API Key Var Name` must be tenant-scoped (`org` unset or `null`).