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

# Update Credential

Replace a credential's body, change its description, or set its `writable` flag.

## **PATCH** `/credentials/:id`

### Path Parameters

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `id` | string | Yes | The unique ID of the credential. |

### Request Body

Send at least one of the fields below, and nothing else. A field not listed here is refused.

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `body` | object | No | Replaces the whole body. Checked against the credential type's schema, as on create. |
| `description` | string | No | Replaces the description. |
| `writable` | boolean | No | Sets the flag. See [Create Credential](https://docs.blobhub.io/rest-api/shared/create-credential.md). |

The credential's `type`, `alias` and target never change.

### Who may send what

| Caller | May send | When |
| :- | :- | :- |
| A caller with `admin` on the credential's target and a human behind the request | `body`, `description` and `writable` | On any credential. |
| The identity whose runs read the credential, with role `write` or higher | `body` alone | Only while the credential is writable. |

The identity whose runs read a credential is the target of the key that starts them: a
[service account](https://docs.blobhub.io/general/service-accounts.md)'s own key for the account's credentials, an organization key for the
organization's, and a blob key for the blob's.

The body-only, writable-only limit holds for a service account's own key at any role, and for any key minted at
`write`. An organization or blob key minted at `admin` passes as the person who minted it, so it also takes the first
row. Mint a key for a refresher at `write`. A service account's own key never takes the first row, even where it
administers the target with `admin`; use an [acting token](https://docs.blobhub.io/rest-api/auth/impersonate.md) when automation has to do that
on a human's behalf.

### Response

| Parameter | Type | Description |
| :- | :- | :- |
| `credential` | object | The credential as listed, without its `body`. |

The `credential` object holds `id`, `created_at`, `target`, `target_id`, `type`, `alias`, `description`, `writable`,
`updated_at` and `updated_by`. When the update was made with an API key it also holds `updated_by_key`, the ID of
that key. The body is never returned.

### Errors

| Status | Error | Cause |
| :- | :- | :- |
| 400 | `invalid_request_body` | An unknown field, an empty object, or a `body` that fails the credential type's schema. |
| 403 | `forbidden` | No access to the credential, or a credential that does not exist. A key below `write`. A credential that is not writable, on the identity's own path. A field other than `body` on that path. A credential deleted in the meantime. |

> [!NOTE]
>
> A run reads the new body from its next node. A node that starts within about a second of the update may still read
> the previous body, so replace a token well before it expires.

### Example

```bash Request theme={null}
curl -X PATCH https://api.blobhub.io/v1/credentials/cred_003 \
  -H "X-API-Key: $SERVICE_ACCOUNT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": {"access_token": "eyJ...", "expires_ms": 1794571200000}}'
```

```json Response theme={null}
{
  "status": "success",
  "credential": {
    "id": "cred_003",
    "created_at": "2026-11-13T09:00:00Z",
    "target": "user",
    "target_id": "user_123",
    "type": "generic",
    "alias": "api-token",
    "description": "Short-lived access token",
    "writable": true,
    "updated_at": "2026-11-13T10:30:00Z",
    "updated_by": "user_123",
    "updated_by_key": "key_001"
  }
}
```


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