> 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/beth/get-started/authentication.md).

# Authentication

[BETH developer Quick Start](/beth/get-started/developer-quick-start.md)

### Authentication surfaces

BETH 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 BETH clients should not need this surface.
* **BitSafe APIs:** obtain account rules and participate in approved mint or redemption workflows.
* **Ethereum account:** initiate deposits to the Ethereum bridge and receive redemptions on the Ethereum network.
* **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

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

### Next step

👉 **Test the connection:** [BETH developer Quick Start](/beth/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.