Tool credentials

The vault behind an authenticated custom tool — the secret is never shown again, only a preview.

Beta

This may change at any time, with a changelog entry and a notice to recent callers — see versioning.

Download the full API pública projection: openapi.json.

Method	Path	What it does
`GET`	`/tool-credentials`	List the workspace’s tool credentials
`POST`	`/tool-credentials`	Create a tool credential
`DELETE`	`/tool-credentials/{id}`	Delete a tool credential
`GET`	`/tool-credentials/{id}`	Fetch one tool credential
`PATCH`	`/tool-credentials/{id}`	Update or rotate a tool credential

`GET /tool-credentials`

List the workspace’s tool credentials

Every credential with its value_preview (never the plaintext), kind, metadata, last_used_at and, while a rotation is in its grace window, rotation_grace_until. Unpaginated, with a total.

curl https://api.vitrinadev.com/api/v1/tool-credentials \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": [
    {
      "id": "a7a7a7a7-0000-4000-8000-000000000002",
      "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
      "name": "weather_api_key",
      "kind": "api_key",
      "value_preview": "••••wx91",
      "metadata": {},
      "created_by": "11111111-0000-4000-8000-000000000001",
      "created_at": "2026-09-12T10:00:00.000Z",
      "updated_at": "2026-09-12T10:00:00.000Z",
      "last_used_at": "2026-09-21T18:04:11.000Z",
      "rotation_grace_until": null
    }
  ],
  "meta": {
    "total": 1
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

name must start with a letter and hold only letters, digits, _ or -; it is unique per workspace and a collision is a 409. value is the plaintext secret — encrypted immediately and never returned again; every later read answers value_preview instead. Reference it from a custom tool’s request_template as $\{secret.NAME\} and set auth_config.credential_id to this row’s id. Answers 201.

Body

Field	Type	Required	Constraints
`name`	string	yes	mín. 2, máx. 64, patrón `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$`
`kind`	`api_key` \	`bearer` \	`basic` \
`value`	string	yes	mín. 1, máx. 16384
`metadata`	object	—

curl -X POST https://api.vitrinadev.com/api/v1/tool-credentials \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weather_api_key",
    "kind": "api_key",
    "value": "wapi_live_abc123wx91"
  }'

Example response (201)

{
  "data": {
    "id": "a7a7a7a7-0000-4000-8000-000000000002",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "name": "weather_api_key",
    "kind": "api_key",
    "value_preview": "••••wx91",
    "metadata": {},
    "created_by": "11111111-0000-4000-8000-000000000001",
    "created_at": "2026-09-12T10:00:00.000Z",
    "updated_at": "2026-09-12T10:00:00.000Z",
    "last_used_at": "2026-09-21T18:04:11.000Z",
    "rotation_grace_until": null
  }
}

Answers: 201 · 400 · 401 · 403 · 404 · 409 · 429

`DELETE /tool-credentials/{id}`

Delete a tool credential

Removes the credential. Any custom tool whose auth_config still points at it starts failing its next call with an auth error — update or disable that tool first. Past tool_invocation audit rows survive unaffected (they carry a redacted snapshot, never the credential itself). 204.

Parameter	In	Type	Required	Constraints
`id`	path	uuid	yes

curl -X DELETE https://api.vitrinadev.com/api/v1/tool-credentials/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

`GET /tool-credentials/{id}`

Fetch one tool credential

Same shape as the list entry — value_preview, never the plaintext.

Parameter	In	Type	Required	Constraints
`id`	path	uuid	yes

curl https://api.vitrinadev.com/api/v1/tool-credentials/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "id": "a7a7a7a7-0000-4000-8000-000000000002",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "name": "weather_api_key",
    "kind": "api_key",
    "value_preview": "••••wx91",
    "metadata": {},
    "created_by": "11111111-0000-4000-8000-000000000001",
    "created_at": "2026-09-12T10:00:00.000Z",
    "updated_at": "2026-09-12T10:00:00.000Z",
    "last_used_at": "2026-09-21T18:04:11.000Z",
    "rotation_grace_until": null
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

`PATCH /tool-credentials/{id}`

Update or rotate a tool credential

Every field optional; at least one is required (an empty body is a 400). Sending value ROTATES the secret: the new value is encrypted, value_preview updates, and the OLD value stays decryptable for a 24-hour grace window (rotation_grace_until) so a tool call already in flight with the old secret does not fail mid-request. name and metadata can be sent alongside value in the same call, or on their own to rename/annotate without rotating.

Parameter	In	Type	Required	Constraints
`id`	path	uuid	yes

Body

Field	Type	Required	Constraints
`name`	string	—	mín. 2, máx. 64, patrón `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$`
`metadata`	object	—
`value`	string	—	mín. 1, máx. 16384

curl -X PATCH https://api.vitrinadev.com/api/v1/tool-credentials/<id> \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "wapi_live_def456zz44"
  }'

Example response (200)

{
  "data": {
    "id": "a7a7a7a7-0000-4000-8000-000000000002",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "name": "weather_api_key",
    "kind": "api_key",
    "value_preview": "••••zz44",
    "metadata": {},
    "created_by": "11111111-0000-4000-8000-000000000001",
    "created_at": "2026-09-12T10:00:00.000Z",
    "updated_at": "2026-09-22T09:00:00.000Z",
    "last_used_at": "2026-09-21T18:04:11.000Z",
    "rotation_grace_until": "2026-09-23T09:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

`GET /tool-credentials`

`POST /tool-credentials`

`DELETE /tool-credentials/{id}`

`GET /tool-credentials/{id}`

`PATCH /tool-credentials/{id}`

On this page