Skip to content
Farcaster

Update or rotate a credential

PUT
/v1/credentials/{id}
curl --request PUT \
  --url https://example.com/v1/credentials/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "auth_type": "bearer", "plaintext": "example", "vault_ref": "example" }'

All fields optional; an absent key leaves it unchanged. A present but empty plaintext is rejected (400) — it would otherwise overwrite the secret with the encryption of zero bytes.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The cred_<uuidv7> credential ID.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

All fields optional; an absent key leaves it unchanged.

object
name

Must not be empty when present.

string
auth_type
string
Allowed values: bearer api_key none
plaintext

Source=managed only. Re-encrypts under the current KEK. Must not be empty when present.

string
vault_ref

Source=vault only.

string

Responses

Section titled “Responses”

200

Section titled “200”

The updated credential.

Media typeapplication/json
object
id
required

The cred_<uuidv7> resource ID.

string
name
required
string
auth_type
required
string
Allowed values: bearer api_key none
source
required
string
Allowed values: managed vault
masked_hint

Present only for source=managed — a redacted hint of the secret, never the secret itself.

string
vault_ref

Present only for source=vault.

string
version
required

Incremented on each rotation.

integer
created_at
required
string format: date-time
updated_at
required
string format: date-time
Example
{
  "auth_type": "bearer",
  "source": "managed"
}

400

Section titled “400”

Invalid body, empty name/plaintext, or invalid auth_type.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object
error
required

A coarse, caller-safe message. Never contains internal state (invariant

string
Examplegenerated
{
  "error": "example"
}

401

Section titled “401”

Missing or invalid bearer token, or the token’s tenant/user claims are absent. No body.

404

Section titled “404”

No resource with this ID exists in the caller’s tenant.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object
error
required

A coarse, caller-safe message. Never contains internal state (invariant

string
Examplegenerated
{
  "error": "example"
}

409

Section titled “409”

The new name conflicts with another credential in the tenant.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object
error
required

A coarse, caller-safe message. Never contains internal state (invariant

string
Examplegenerated
{
  "error": "example"
}

500

Section titled “500”

An unexpected server-side error. No body (internal detail is never returned to callers, invariant