> For the complete documentation index, see [llms.txt](https://docs.bitsafe.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitsafe.finance/cbtc-1/get-started/authentication.md).

# Authentication

[CBTC developer Quick Start](/cbtc-1/get-started/developer-quick-start.md)

### Authentication surfaces

CBTC integrations can authenticate to more than one service:

* **Canton Ledger API:** submit commands and query contract state for an authorized party.
* **Canton Admin API:** perform privileged participant operations such as package management. Most CBTC clients should not need this surface.
* **BitSafe APIs:** obtain account rules and participate in approved mint or redemption workflows.
* **Source and artifact systems:** access approved repositories or private release artifacts where required.

### Use separate identities

Use distinct clients and credentials for development, test, and production. Separate administrative credentials from application credentials. Grant only the party rights and API scopes required for the workflow.

### Configuration categories

A client can require an identity-provider URL, realm or audience, client identifier, client secret or approved key, grant type, token endpoint, Canton user, and target party. Exact variable names belong in the versioned configuration reference.

### Safe setup

1. Create or obtain the approved service identity.
2. Assign the minimum Canton `actAs` and `readAs` rights.
3. Configure the approved audience and scopes.
4. Store secrets in a secret manager or protected local store.
5. Request a token through the approved flow.
6. Validate issuer, audience, expiry, and party authorization.
7. Run a read-only balance query before submitting a command.

### Operational rules

* Never place tokens or secrets in documentation, screenshots, logs, shell history, or source control.
* Rotate credentials under an approved process.
* Treat authentication success and party authorization as separate checks.
* Do not retry a state-changing command only because token refresh or transport failed.
* Sanitize support evidence before sharing it.

### Common failures

| Failure                         | Check                                                                  |
| ------------------------------- | ---------------------------------------------------------------------- |
| Token request rejected          | Provider URL, client, secret, grant, realm, and network access         |
| Token accepted but query denied | Audience, scopes, Canton user rights, and party                        |
| Works in one environment only   | Environment-specific client, endpoints, trust store, and party mapping |
| Intermittent failures           | Clock skew, token expiry, refresh behavior, and connection reuse       |

### Related pages

* [CBTC environments and prerequisites](/cbtc-1/get-started/environments-and-prerequisites.md)
* [CBTC developer Quick Start](/cbtc-1/get-started/developer-quick-start.md)
* [Install and validate CBTC DARs](/cbtc-1/get-started/install-and-validate-dars.md)
* [CBTC SDK, API, and integration reference](/cbtc-1/concepts-and-reference/sdk-api-and-integration-reference.md)
* [CBTC security](/cbtc-1/concepts-and-reference/security.md)

### Next step

👉 **Test the connection:** [CBTC developer Quick Start](/cbtc-1/get-started/developer-quick-start.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bitsafe.finance/cbtc-1/get-started/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.