Skip to content

Lexe Client Credentials

Lexe client credentials are the recommended way to authenticate a Lexe wallet from an app or service. They are scoped, revocable, and may have budgets attached, so an app gets exactly the access it needs, without the responsibility of holding the root seed or managing backup and restore.

A client credential is a long, opaque string that looks like this: eyJ1c2VyX3BrIjoiNmZkNzY0MTU2OTMwNTA5ZmFkNTM2MWQzYjIyYjYxZjc1YWE5MWVkNjQwMjE1YjJjNDFjMmZmODZiMmJmYzQ3MiIsImxleGVfYXV0aF90b2tlbiI6IjlkVENVdkM4eTdxY055VWJxeW56M253SVFRSGJRcVBWS2VNaFhVajFBZnItdmdqOUUyMTdfMnRDUzFJUU03T...

Credential scopes and budgets

Credential scopes define what a credential can do, such as reading the wallet, receiving payments, or spending. Your app requests only the scopes it needs, and the user sees exactly what they are granting.

Budgets will add a spending limit, such as 20 USD per month, so a credential with the spend scope can only spend what the user allowed. Budgets are not yet available.

Getting a credential

There are three ways for your app to get a credential for a wallet:

  • LexeConnect (recommended): If your app or service needs access to your users' wallets, use LexeConnect. Your app requests the scopes it needs, the user approves them in one tap, and your app receives a credential with exactly those scopes.
  • Lexe app: A user can create a credential manually and paste it into your app. In the Lexe app's left sidebar, they select "Client credentials", create a credential with the scopes your app needs, and add a label to remind them what it was for. This is also the easiest way to create a credential for your own wallet while developing.
  • Programmatically: Credentials can also be created with the CLI (lexe create-client), the SDKs, or the sidecar (POST /v2/node/create_client).

Lexe app sidebar with the client credentials entry highlighted

Using a credential

Client credentials can be used with Lexe's SDKs, the CLI, and the sidecar.

  • CLI: Pass via --client-credentials or --client-credentials-path, or set via env (LEXE_CLIENT_CREDENTIALS or LEXE_CLIENT_CREDENTIALS_PATH), or store in .env in the current or any parent directory.
  • Sidecar: Set default credentials via CLI (--client-credentials, --client-credentials-path) or env (LEXE_CLIENT_CREDENTIALS, LEXE_CLIENT_CREDENTIALS_PATH), or store in .env in the current or any parent directory, or pass per-request via the Authorization: Bearer <credentials> header. Per-request credentials take precedence over default credentials if provided, and are useful for controlling multiple wallets from a single sidecar process.
  • SDK: Construct the ClientCredentials and pass it into LexeWallet. See the Rust quickstart or the Python quickstart for an example.

When using a user's client credential, remember that you are acting from the wallet owner's perspective. If you instantiate a LexeWallet with a user's client credential, calling LexeWallet.pay(_) will spend the user's funds, not your own. If you need to charge the user's wallet for a good or service, you can do so by using the user's wallet to pay your own.

Revocation

A user can revoke your app's credential at any time from the same "Client credentials" page in the Lexe app, by pressing the delete button. Revocation takes effect at the user's node, which blocks any further use of the credential, so there is nothing for your app to delete on its side. Expect revoked credentials to stop working, and offer the user a way to reconnect.

Client credentials page with the delete button highlighted

Credentials can also be revoked programmatically with the CLI (lexe revoke-client), the SDKs, or the sidecar (POST /v2/node/revoke_client).