---
title: "What material this Mac holds for each credential, per role"
method: GET
path: "/v1/credentials/roles"
tags: ["Credentials"]
---

# What material this Mac holds for each credential, per role

`GET /v1/credentials/roles`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/credentials/roles`
- Auth: HTTP bearer

The presence map. Answers what EXISTS, never what the values are: a
role reports `configured`, `absent` or `unreadable` and the response
has no field a secret could occupy.

`unreadable` is distinct from `absent` on purpose. It means a pending
transaction or an unreadable Keychain item, and reporting that as
absence would invite a re-entry that overwrites material still on
disk. Declared roles are listed even when unreadable, because omitting
one renders a role mid-transaction as one the user never configured.

## Response `200`

Every credential identity and its declared roles, ordered by roleId

- CredentialRolesResponse
  - `credentials` CredentialRoles[], required
    - `credentialId` string, required
    - `roles` CredentialRoleStatus[], required
      - `roleId` string, required: Stable catalog role id (`workers-ai`). Never a display label.
      - `kind` string, required: The material kind this role holds. An unknown kind renders as unsupported and selects no other role.
      - `presence` 'configured' | 'absent' | 'unreadable', required: `unreadable` is a pending transaction or an unreadable Keychain item, never absence.
      - `accountBinding` string: The service account this role's token was bound to at save time.
      - `publicId` string: A composite credential's public half, carried on the same role as its secret.
      - `revision` integer, required: Committed revision, so a later use can be fenced against the exact material the caller saw.

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)