Skip to content
Farcaster

Store a new upstream credential

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

plaintext (source=managed) is envelope-encrypted before any persistence and never appears in any response (invariant #4).

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
auth_type
required
string
Allowed values: bearer api_key none
source
required
string
Allowed values: managed vault
plaintext

Required when source=managed. Envelope-encrypted before persistence; never returned.

string
vault_ref

Required when source=vault. Opaque path in the external secrets store.

string

Responses

Section titled “Responses”

201

Section titled “201”

Credential created.

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, missing name/auth_type, or a source/plaintext/vault_ref mismatch.

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.

409

Section titled “409”

A credential with this name already exists 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