# Credential HTTP API

> Public endpoint reference for provider discovery, setup, Credential creation, authorization, 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 authorization |

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 |

Non-import providers reject caller material.

## 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 |
| POST | `/authorize` | Begin or continue interactive authorization |
| POST | `/revoke` | Revoke one version or all usable versions |
| GET | `/consumers` | List Resources that reference the Credential |
| GET | `/uses` | List bounded recent injection records |
| GET | `/events` | List bounded lifecycle events |

## Public authorization callback {#authorization-callback}

`GET /v1/credential-authorizations/callback` is called by the external authorization service. It validates signed state and redirects to the Console Credential page. Client applications should never call it directly.

## 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.