Credential HTTP API
Public endpoint reference for provider discovery, setup, Credential creation, interaction, lifecycle, and inspection.
Every namespace endpoint requires authenticated authority and its corresponding Policy action. Secret material is accepted only by creation or version endpoints and is never returned.
Provider endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/namespaces/:namespace/credential-provider-catalog | List packages visible to the tenant |
| GET | /v1/namespaces/:namespace/credential-providers | List installed providers |
| POST | /v1/namespaces/:namespace/credential-providers/install | Install one package instance |
| GET | /v1/namespaces/:namespace/credential-providers/:id | Read an installed provider |
| POST | /v1/deployments | Upload a custom provider archive or Git snapshot request |
Provider setup accepts either existing bootstrap Credential references or one-time inline material. Inline material is converted to encrypted Credentials and removed before the provider Resource reaches the registry.
Credential collection
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/namespaces/:namespace/credentials | List Credential Resources |
| POST | /v1/namespaces/:namespace/credentials | Create, mint, or begin provider interaction |
Creation fields are:
| Field | Required | Meaning |
|---|---|---|
id | Yes | Lowercase Credential name |
provider | Yes | Installed CredentialProvider CRN |
configuration | Yes | Non-secret object validated by the provider schema |
material | Import only | Secret value for an import provider |
policies | No | Credential Policy attachments |
returnUrl | No | Interactive providers only: where the interaction callback returns the browser instead of the Console |
Non-import providers reject caller material.
A returnUrl is an https URL of at most 2048 characters with no fragment, whose origin is one of the tenant's return origins. Any other value is refused with 422 before anything is created. POST /interact accepts the same returnUrl when it begins an interaction and ignores it when it submits an event to a session. When a new start reuses the caller's open session, the newest request's returnUrl, or its absence, applies.
Credential item and lifecycle
| Method | Suffix after /credentials/:id | Purpose |
|---|---|---|
| GET | none | Read authoritative metadata |
| POST | /versions | Add imported material as a scheduled version |
| POST | /activate | Activate a scheduled version |
| POST | /rotate | Ask the pinned provider to mint a replacement |
| GET | /interact?session=:session | Read or resume the current interaction step |
| POST | /interact | Begin an interaction or submit its next event |
| POST | /revoke | Revoke one version or all usable versions |
| GET | /consumers | List Resources that reference the Credential |
| GET | /uses | List use records of the current Credential, 200 per page; ?after= takes the next cursor, ?id= reads one use |
| GET | /events | List bounded lifecycle events |
GET /uses answers { uses, next, lastUseAt }. Each use is { id, version, fingerprint, origin, resource, pos, destination, binding, outcome, at }, and its id is 64 hex characters. A use appears once the use archive rolls its file, within 60 seconds, and lastUseAt is the time of the latest recorded one. A Credential created again under the same id lists only the uses of its new life. The Credential's metadata does not carry lastUseAt.
Public interaction callback
GET or POST /v1/credential-interactions/callback is called by an external service. It validates signed state and advances the Credential-owned session. GET redirects to the interaction's returnUrl with credential (the Credential id), interaction (complete, pending, or failed), session, and on failure reason (the HTTP status) set on its query. An interaction started without a returnUrl redirects to the Console Credential page with the same interaction, session, and reason. POST returns bounded acceptance status. Client applications should not manufacture callback requests.
An interaction started with a returnUrl finishes only in the browser that started it. Its callback is held, not applied: the redirect to the returnUrl carries interaction=pending and a one-time confirm code, and the interaction stays pending until the principal that started it sends POST /interact with { "session": "...", "event": { "kind": "confirm", "code": "..." } }, which applies the held callback and answers as that step does. A later callback replaces the held one and its code, and a wrong or spent code is refused with 409. The product should redeem the code only in the browser session that began the interaction, for example by checking a cookie it set when it did, so a link followed elsewhere never completes it.
An interaction response contains the opaque session ID and one provider action: redirect, form, display, wait, or complete. Send only the matching event—submit, continue, or poll—back to /interact. External callbacks are delivered by the public callback endpoint.
Responses and errors
Successful responses contain stable identity, lifecycle status, version metadata, expiry, fingerprints, and operation results. They never contain Credential material or provider-private state. See States and errors for operational handling.
Download the credential OpenAPI document for a machine-readable path and schema index.