# 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 {#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 {#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](/docs/api/customers#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 {#credential-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 {#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 {#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](/docs/credentials/reference/states-errors.md) for operational handling.

Download the [credential OpenAPI document](/docs/credentials/reference/openapi.yaml) for a machine-readable path and schema index.