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

# Credentials

> How Craft Agents stores sensitive data securely

Craft Agents stores API keys, OAuth tokens, and other sensitive credentials in an encrypted file on your machine.

## Location

```
~/.craft-agent/credentials.enc
```

## Encryption

Credentials are encrypted using:

* **Algorithm**: AES-256-GCM
* **Key derivation**: PBKDF2 with machine-specific seed
* **Security model**: Same protection level as OS keychains, without interactive prompts

The encryption key is derived from machine-specific identifiers, meaning the credentials file can only be decrypted on the same machine where it was created.

## Key Format

Credentials are stored with keys using different formats depending on scope:

**Global credentials (2-part key):**

```
{type}::global
```

**Source credentials (3-part key):**

```
{type}::{workspaceId}::{sourceId}
```

**LLM connection credentials (2-part key):**

```
{type}::{connectionSlug}
```

Where `type` identifies the credential type, `workspaceId` is the workspace UUID, and `sourceId` is the source identifier.

## Credential Types

| Type                  | Description                                                            | Scope          |
| --------------------- | ---------------------------------------------------------------------- | -------------- |
| `anthropic_api_key`   | API key for the AI provider (Anthropic, OpenRouter, Vercel, or custom) | Global         |
| `claude_oauth`        | Claude OAuth token (Pro/Max subscription)                              | Global         |
| `llm_api_key`         | API key for an LLM connection                                          | Per connection |
| `llm_oauth`           | OAuth token for an LLM connection                                      | Per connection |
| `llm_iam`             | AWS IAM credentials for Bedrock                                        | Per connection |
| `llm_service_account` | GCP service account JSON for Vertex                                    | Per connection |
| `source_oauth`        | Source OAuth token                                                     | Per source     |
| `source_bearer`       | Source bearer token                                                    | Per source     |
| `source_apikey`       | Source API key                                                         | Per source     |
| `source_basic`        | Source basic auth                                                      | Per source     |

<Note>
  `anthropic_api_key` and `claude_oauth` are legacy global credentials. New installations store credentials per LLM connection.
</Note>

## Examples

```
anthropic_api_key::global
claude_oauth::global
llm_api_key::anthropic-api
llm_oauth::claude-max
llm_iam::bedrock
source_oauth::ws-abc123::github
source_bearer::ws-abc123::api-service
```

## Credential Scoping

Credentials are scoped at two levels:

```
LLM Connections (2-part key)
  llm_api_key::anthropic-api
  llm_oauth::claude-max

Source (3-part key: type::workspaceId::sourceId)
  source_oauth::ws-abc123::github
  source_bearer::ws-abc123::exa
```

This means:

* LLM connection credentials are tied to a specific connection slug
* Source credentials are specific to a source within a workspace, using the 3-part key format

<Note>
  Legacy global credentials are migrated automatically into LLM connection credentials:

  * `anthropic_api_key::global` → `llm_api_key::anthropic-api`
  * `claude_oauth::global` → `llm_oauth::claude-max`
</Note>

## Viewing Stored Credentials

You can see what credentials are stored (but not their values):

```
> /debug
```

Shows credential identifiers like:

```
Credentials:
  anthropic_api_key::global
  source_oauth::ws-abc123::github
```

## Managing Credentials

### Adding Credentials

Credentials are added automatically when you:

* Complete the setup wizard (API key or OAuth)
* Connect to a source requiring authentication
* Authenticate with an MCP server

### Removing Credentials

To clear all credentials, delete the credentials file:

```bash theme={null}
rm ~/.craft-agent/credentials.enc
```

This removes all stored credentials. You'll need to re-authenticate on next launch.

## Security Considerations

<AccordionGroup>
  <Accordion title="File permissions">
    The credentials file is created with restricted permissions (readable only by your user). Verify with:

    ```bash theme={null}
    ls -la ~/.craft-agent/credentials.enc
    # Should show -rw-------
    ```
  </Accordion>

  <Accordion title="Backup considerations">
    If you backup your home directory, the credentials file is included but encrypted. It cannot be decrypted on a different machine.
  </Accordion>

  <Accordion title="Machine migration">
    When moving to a new machine, you'll need to re-enter credentials. The encrypted file from your old machine won't work.
  </Accordion>

  <Accordion title="Shared accounts">
    If multiple users share a system account, they share the same credentials file. Use separate user accounts for isolation.
  </Accordion>
</AccordionGroup>

## Environment Variable Override

For automation or CI environments, you can provide credentials via environment variables:

| Variable                   | Purpose                                                       |
| -------------------------- | ------------------------------------------------------------- |
| `ANTHROPIC_API_KEY`        | Anthropic API key                                             |
| `CRAFT_ANTHROPIC_API_KEY`  | Anthropic API key (takes precedence over `ANTHROPIC_API_KEY`) |
| `CRAFT_CLAUDE_OAUTH_TOKEN` | Claude OAuth token (for Claude Max subscriptions)             |

Environment variables take precedence over stored credentials.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Credential not found errors">
    The credential may have been removed or corrupted. Re-enter it:

    * For API keys: Open Settings and re-enter your key
    * For OAuth: Re-authenticate when prompted
  </Accordion>

  <Accordion title="Cannot decrypt credentials">
    This usually means the file was copied from another machine. Delete the credentials file and re-enter credentials:

    ```bash theme={null}
    rm ~/.craft-agent/credentials.enc
    ```
  </Accordion>

  <Accordion title="File permission errors">
    Fix permissions:

    ```bash theme={null}
    chmod 600 ~/.craft-agent/credentials.enc
    ```
  </Accordion>
</AccordionGroup>