# CredentialProvider SDK reference

> TypeScript contract reference for provider metadata, schemas, operations, lifecycle results, setup hints, and context capabilities.

Import CredentialProvider contracts from `@constal/sdk`. The package validates definitions at module load and the managed builder validates the probed metadata again before catalog publication.

## Primary exports {#primary-exports}

| Export | Purpose |
| --- | --- |
| `credentialProvider(definition)` | Build and validate a provider Driver |
| `credentialProviderConfigSchema(schema)` | Validate the supported non-secret schema subset |
| `credentialProviderSetupMetadata(value, slots)` | Validate optional Console presentation metadata |
| `CredentialProviderDefinition` | Complete author contract |
| `CredentialProviderPackageMetadata` | Probed immutable package metadata |
| `CredentialProviderCatalogEntry` | Package reference, management, Driver, schemas, and metadata |
| `CredentialMintRequest` / `CredentialMintResult` | Mint and refresh contract |
| `CredentialAuthorizationBeginRequest` | Begin browser authorization |
| `CredentialAuthorizationCompleteRequest` | Complete browser authorization |
| `CredentialMaterialRequest` | Verify or destroy one version |

## Definition fields {#definition-fields}

`id`, `version`, `displayName`, `description`, `credentialSlots`, `configSchema`, `credentialConfigSchema`, `rotation`, `egress`, and `mint` are required. `documentationUrl`, `setup`, `authorization`, `mintRecovery`, `verify`, and `destroy` are optional according to provider behavior.

## Driver context {#driver-context}

Provider callbacks use the ordinary Driver context. Important capabilities include:

- `secret(slot)` for declared bootstrap Credential material;
- `egress(request)` for bounded allowlisted HTTPS operations;
- `audit(event)` for non-secret provider audit details.

Provider code does not receive direct database, vault, queue, analytics, tenant registry, or CredentialCoordinator bindings.

## Result rules {#result-rules}

Mint and authorization completion return non-empty `material`, optional positive `expiresAt`, and optional private lifecycle state. Verification returns `{ verified: boolean }`. Destruction returns `{ destroyed: boolean }`.

Do not include access material inside private state or refresh tokens inside consumer material. Keep the two lifecycles separated.

## Resource selectors {#resource-selectors}

`ScopedCredentialRef` declares `kind: "scoped"`, a logical key, explicit owner scope, and `required: true`. `ScopedResourceRef` additionally pins a Resource contract. Read [Scoped bindings](/docs/credentials/scoped-bindings.md) for resolution semantics.

## Machine-readable schemas {#machine-readable-schemas}

- [Credential creation schema](/docs/credentials/reference/credential-create.schema.json)
- [Provider installation schema](/docs/credentials/reference/provider-install.schema.json)
- [Provider setup metadata schema](/docs/credentials/reference/provider-setup.schema.json)