# Credentials

> Securely acquire, store, rotate, select, and use external authority from Constal agents.

Constal separates **who may invoke an agent** from **what external authority the agent may use**. An AuthProvider authenticates an incoming caller. A CredentialProvider acquires and maintains outbound secret material. A Credential stores that material as governed versions. A scoped binding selects the correct Resource or Credential for the authenticated tenant, customer, or principal.

## Choose a path {#choose-a-path}

| What you need | Start here |
| --- | --- |
| Store an API key, token, password, or signing secret you already have | [Store an existing secret](/docs/credentials/store-secret.md) |
| Let a person grant access through OAuth | [Authorize an OAuth credential](/docs/credentials/oauth/authorize.md) |
| Run unattended automation with application or installation authority | [Choose an authentication model](/docs/credentials/choose-authentication.md) |
| Serve multiple customers or users from one agent | [Scoped bindings](/docs/credentials/scoped-bindings.md) |
| Build a custom acquisition and rotation lifecycle | [Build a CredentialProvider](/docs/credentials/providers/build.md) |
| Diagnose a failed setup, renewal, or authorization | [Troubleshooting](/docs/credentials/troubleshooting.md) |

## Mental model {#mental-model}

```text credential relationships
CredentialProvider  → creates and maintains → Credential
Resource            → consumes             → Credential
Scoped binding      → selects              → Resource or Credential
Agent               → invokes              → Resource
```

A Credential is deliberately opaque. Constal encrypts and versions its material, but only the consuming Driver decides whether the bytes represent an API key, OAuth token, private key, password, or another secret.

## Common examples {#common-examples}

- A tenant-wide model gateway uses one imported API-key Credential.
- A customer-scoped GitHub Resource uses that customer's GitHub App installation Credential.
- A principal-scoped GitHub Resource uses the signed-in person's OAuth Credential.
- A CredentialProvider uses a bootstrap Credential, such as an application client secret, to create many output Credentials.

## Next steps {#next-steps}

Read [the complete mental model](/docs/credentials/mental-model.md), then follow the guide matching your authentication model. If an agent serves multiple owners, read [scoped bindings](/docs/credentials/scoped-bindings.md) before deploying its Resource selectors.