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

# Save a credential profile

> Create or replace encrypted agent credentials and return the new profile version.

## Authentication

Send your scoped bearer token in the `Authorization: Bearer <BEAD_TOKEN>` header, or send your API key in `X-API-Key`.

## Parameters

**id** `string` *required*

UUID of the credential profile. Format: `uuid`.

## Request body

The JSON body is required.

**name** `string` *required*

Profile display name; 1–100 bytes, cannot start with env: or contain secret values. Minimum length: `1`. Maximum length: `100`.

**material** `object` *required*

Encrypted credential material; use a credential pool or legacy env/codexAuth, not both.

**Properties**

**env** `object`

Nonempty agent API keys under OPENAI\_API\_KEY, CODEX\_API\_KEY, ANTHROPIC\_API\_KEY, or CLAUDE\_CODE\_OAUTH\_TOKEN. Additional keys accept `string` values.

**credentials** `object[]`

Ordered credential pool, at most 64 entries; cannot be combined with env or codexAuth.

**Properties**

**type** `string` *required*

Credential format. Allowed values: `"apiKey"`, `"claudeOauth"`, `"codexAuth"`.

**provider** `string`

API key provider; custom providers require models and a baseUrl.

**models** `string[]`

Models routed to this API key; at most 128 names.

**key** `string`

API key secret for an apiKey entry.

**baseUrl** `string`

Optional HTTPS API origin; cannot include credentials, query, or fragment.

**accessToken** `string`

OAuth access token for a claudeOauth entry.

**refreshToken** `string`

Optional OAuth refresh token.

**expiresAt** `integer`

OAuth expiration as Unix seconds.

**auth** `string`

Codex authentication JSON with tokens.access\_token and tokens.account\_id for a codexAuth entry.

**codexAuth** `string`

A JSON object encoded as a string, in the Codex authentication format.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl --request PUT \
  --url "https://api.bead.run/credential-profiles/$PROFILE_ID" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "build-agent",
  "material": {
    "env": {
      "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"
    }
  }
}
JSON
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
from beadrun import Bead

client = Bead()
result = client.profiles.put("fe1593e7-c31e-4cdd-96df-80ef26fa1275", "build-agent", {"env": {"OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"}})
client.close()
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
import { Bead } from "@beadrun/sdk";

const client = new Bead();
const result = await client.profiles.put("fe1593e7-c31e-4cdd-96df-80ef26fa1275", "build-agent", {"env": {"OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"}});
```

## Response

### 200

Profile saved with an incremented version.

**id** `string` *required*

Profile UUID.

**name** `string` *required*

Display name for the profile.

**version** `integer` *required*

Version incremented when credentials are replaced or revoked.

**revoked** `boolean` *required*

Whether delivery of this profile has been revoked.

## Errors

| Status | Meaning |
| - | - |
| 400 | Invalid resource UUID or request parameters. |
| 401 | Authentication credential is missing or rejected. |
| 403 | The credential lacks the required scope. |
| 404 | The requested resource does not exist or is outside your organization. |
| 409 | The profile is managed by another credential flow or its state conflicts with this write. |
| 413 | Request body exceeds the route limit. |
| 429 | Request or resource admission limit exceeded (`admission_limit`; trial capacity can return `free_capacity_full`). Follow limit.next\_action and Retry-After when present. |
| 500 | Credential profile metadata could not be serialized. |
| 503 | Service or persistence is temporarily unavailable. |


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