# Constal credential documentation

> Credentials, CredentialProviders, scoped bindings, lifecycle, integrations, security, SDK and HTTP reference for Constal.

## Start here

- [Credentials](https://constal.ai/docs/credentials.md): Securely acquire, store, rotate, select, and use external authority from Constal agents.
- [Credential mental model](https://constal.ai/docs/credentials/mental-model.md): Understand Credentials, CredentialProviders, Resources, bindings, AuthProviders, and their security boundaries.
- [Choose an authentication model](https://constal.ai/docs/credentials/choose-authentication.md): Select imported, application, installation, or user-delegated authority for an integration.

## Use credentials

- [Store an existing secret](https://constal.ai/docs/credentials/store-secret.md): Import an API key, token, password, private key, or signing secret as an encrypted Credential.
- [Use a credential from an agent](https://constal.ai/docs/credentials/use-from-agent.md): Bind a Credential to a governed Resource and expose only Resource operations to agent code.
- [Set up a credential provider](https://constal.ai/docs/credentials/providers/setup.md): Install a provider package, configure its application details, and securely bind bootstrap secrets.
- [Authorize an OAuth credential](https://constal.ai/docs/credentials/oauth/authorize.md): Create a durable per-user Credential through a provider-managed browser authorization flow.

## Scope and bindings

- [Scoped bindings](https://constal.ai/docs/credentials/scoped-bindings.md): Select the correct Resource or Credential for an authenticated tenant, customer, or principal.

## Lifecycle

- [Credential lifecycle](https://constal.ai/docs/credentials/lifecycle.md): Understand active versions, renewal, overlap, replacement, reconnect, disable, and permanent revocation.

## Providers

- [Build a CredentialProvider](https://constal.ai/docs/credentials/providers/build.md): Implement, test, package, and privately deploy custom credential lifecycle code.
- [Provider configuration schemas](https://constal.ai/docs/credentials/providers/schemas.md): Define setup configuration, per-Credential parameters, secret slots, labels, help, defaults, and optional fields.
- [Provider authorization lifecycle](https://constal.ai/docs/credentials/providers/authorization.md): Implement safe browser authorization with signed state, PKCE, callback validation, private refresh state, and recovery.
- [Provider package format](https://constal.ai/docs/credentials/providers/package-format.md): Reference for CredentialProvider manifests, archives, Git sources, immutable builds, and private catalog publication.

## Integrations

- [Choose a GitHub credential](https://constal.ai/docs/credentials/integrations/github.md): Decide between GitHub App installation authority and GitHub user OAuth for your agent workload.
- [GitHub App installation credentials](https://constal.ai/docs/credentials/integrations/github/github-app.md): Configure a tenant-owned GitHub App and mint short-lived installation tokens for unattended agents.
- [GitHub user OAuth credentials](https://constal.ai/docs/credentials/integrations/github/github-user-oauth.md): Configure GitHub App user authorization and create one renewable Credential for each consenting user.

## Security

- [OAuth callback security](https://constal.ai/docs/credentials/oauth/callback.md): Understand the shared Credential authorization callback, tenant routing, signed state, PKCE, and replay protection.
- [Credential security](https://constal.ai/docs/credentials/security.md): Security guarantees and operator responsibilities for storage, use, lifecycle state, logs, and tenant isolation.

## Reference

- [Credential HTTP API](https://constal.ai/docs/credentials/reference/http-api.md): Public endpoint reference for provider discovery, setup, Credential creation, authorization, lifecycle, and inspection.
- [CredentialProvider SDK reference](https://constal.ai/docs/credentials/reference/sdk.md): TypeScript contract reference for provider metadata, schemas, operations, lifecycle results, setup hints, and context capabilities.
- [Credential states and errors](https://constal.ai/docs/credentials/reference/states-errors.md): Operational reference for status, version states, setup failures, binding failures, and authorization recovery.
- [Credential troubleshooting](https://constal.ai/docs/credentials/troubleshooting.md): Diagnose provider setup, OAuth callbacks, scoped resolution, rotation, and Resource use from observable symptoms.