> For the complete documentation index, see [llms.txt](https://help.enterprise.ledger.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.enterprise.ledger.com/help-center-v2/start-here/get-started/api-users.md). # API users What an API user is on Ledger Enterprise, the API Operator and API Administrator roles, how an API user authenticates and approves, and what the API offers. This page explains how an API user works, from its credentials to its approvals. **Role: Master Administrators create API users. Your own systems operate them.** ## What an API user is An API user is a user with no Ledger device. It works only through the API, with a key pair that your organization generates and holds. A Master Administrator creates the API user in **Users**, from the public key of that pair. Ledger Enterprise receives only the public key. The creation is a Request, and the Master Administrator quorum approves it. See [**Creating an API user**](/help-center-v2/administration/users.md#creating-an-api-user). An API user cannot sign in to the interface, because sign-in there needs a Ledger device. It reads, creates and approves over the API only. ## API Operator and API Administrator An API user takes one of two roles, as a Personal Security Device (PSD) user does. | | API Operator | API Administrator | | ------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Role | Operator | Administrator | | What it can do | The same Requests as a PSD Operator. The Rules of each Account decide what it can create and approve there | Nothing by default. The **API admin rules** give it permissions | | Where its permissions come from | The Account Rules and groups that name it | The **API admin rules** in [**Workspace settings**](/help-center-v2/administration/governance/workspace-settings.md#api-admin-rules) | The **API admin rules** have one Rule: the **Policy-based account creation rule**. The API Administrators in its first step can create an Account from an existing Policy. The API Administrators in its later steps approve the Request. See [**Creating and editing Accounts**](/help-center-v2/guides/accounts/creating-and-editing-accounts.md). An API Administrator cannot be a Master Administrator. It cannot edit an Account. It cannot create or change Policies, Whitelists, groups or users. ## How an API user authenticates An API user holds two separate secrets. Each has one purpose. | Secret | Where it comes from | What it does | | ------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------- | | **API key ID** and **API key secret** | A Master Administrator issues them with **Refresh credentials** | Authenticates the API user | | Private key | Your organization generates it. Its public key is registered when the API user is created | Signs each approval | To authenticate, the integration sends the API key ID, the API key secret and the Workspace name. It gets back an access token, which is a JSON Web Token (JWT), and a refresh token. Each token comes with its validity period, in seconds. The integration uses the refresh token to get new tokens. The API key ID and secret cannot approve a Request on their own. An approval needs a signature made with the private key. > **Important:** Creating an API user does not issue an API key ID or secret. After the creation Request is approved, a Master Administrator selects **Refresh credentials** to issue the first pair. See [**Issuing the first API credentials**](/help-center-v2/administration/users.md#issuing-the-first-api-credentials). A refresh issues a new pair and stops the old pair immediately. The platform logs each refresh. ## How an API user approves An API user approves a Request with a signature, as a PSD user does. The difference is where the key is. 1. Get the approval challenge of the Request. 2. Sign the challenge with the private key. 3. Send the signature to approve the Request. The platform checks the signature against the public key registered for the API user. It refuses an approval with an invalid signature. The same Rules, steps and quorums apply to every user. An API user approves only at a step that names it, and only while that step is the current one. To reject a Request, see [**Rejecting**](/help-center-v2/guides/requests.md#rejecting). An API user has no Ledger device, so no second screen shows the operation before the signature. Your own systems must check what they sign. See [**The security model**](/help-center-v2/concepts/the-security-model.md). To verify a deposit address, an API user uses the Workspace root Certificate Authority (CA). A Master Administrator enables this once. See [**Enable address verification for API users**](/help-center-v2/administration/governance/workspace-settings.md#enable-address-verification-for-api-users). ## What the API offers The API also offers the capabilities below. For each one, see the [**API documentation**](https://help.enterprise.ledger.com/api-documentation-v2). | Capability | Notes | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Allowed actions | Returns the actions a user can perform on an Account or another resource. In the interface, an action you cannot perform is unavailable | | Fee estimate | Estimates the fees of a transaction before you create its Request | | Sanctions check | Checks a transaction against sanctions screening before you create its Request. The result is `OK` or `SANCTIONED`. The platform runs the same check when the Request is created, and refuses a sanctioned transaction | | Balances of several Accounts | Returns the balances of many Accounts in one call | | Transaction Check risk level | Sets the highest risk level that the Creator accepts for an EVM transaction. If the check returns a higher level, the creation fails. Without this setting, any result is accepted. See [**Sending assets**](/help-center-v2/guides/transactions/sending-assets.md) | | Account creation from a Policy | API Administrators in the **Policy-based account creation rule** only | ## What can go wrong | Situation | What to do | | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | The API user exists but cannot authenticate, and nobody issued credentials | A Master Administrator selects **Refresh credentials** to issue the first pair | | The API key secret is lost | A Master Administrator selects **Refresh credentials** again. The old pair stops working immediately | | **Refresh credentials** is not available | It is available only for an active API user who is not suspended | | The private key is lost or exposed | The public key of an API user cannot be changed. Create a new API user with a new public key, then revoke the old API user | | An API Administrator gets an authorization error | By default an API Administrator has no permissions. Check that the **Policy-based account creation rule** names it | ## Related * [**Users**](/help-center-v2/administration/users.md) * [**Workspace settings**](/help-center-v2/administration/governance/workspace-settings.md) * [**Requests and approvals**](/help-center-v2/guides/requests.md) * [**How governance works**](/help-center-v2/concepts/how-governance-works.md) * [**The security model**](/help-center-v2/concepts/the-security-model.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://help.enterprise.ledger.com/help-center-v2/start-here/get-started/api-users.md?ask=&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.