cheqd Studio

ℹ️ Overview

cheqd Studio (formerly known as Credential Service) enables users to consume cheqd's identity functionality, such as DIDs, Trust Registries, Status Lists, Credential Payments and DID-Linked Resources over REST API. This enables users to integrate cheqd's functionality into existing applications or create a full end-to-end trusted ecosystem from the ground up.

Get started by setting up your cheqd Studio account below:

• Setup cheqd Studio account
• cheqd Studio docs and tutorials

📖 Usage

We run hosted endpoints for this package (in case you don't want to run it yourself) which have Swagger / OpenAPI definition endpoints that list all of the APIs and how they work.

The Swagger API definition pages are:

• Production / Stable Release APIs
• Staging / Development Release APIs

🔧 Configuration

The application allows configuring the following parameters using environment variables.

Core configuration

Events tracking

1. LOG_LEVEL: specifies log level, like 'trace', 'debug', 'info', 'warn' or 'error';

Network API endpoints

1. MAINNET_RPC_URL: RPC endpoint for cheqd mainnet (Default: https://rpc.cheqd.net:443).
2. TESTNET_RPC_URL: RPC endpoint for cheqd testnet (Default: https://rpc.cheqd.network:443).
3. RESOLVER_URL: API endpoint for a DID Resolver endpoint that supports did:cheqd (Default: https://resolver.cheqd.net/1.0/identifiers/).
4. APPLICATION_BASE_URL: URL of the application (external domain name).
5. CORS_ALLOWED_ORIGINS: CORS allowed origins used in the app (optional). (Default: APPLICATION_BASE_URL).

Veramo KMS Database

The application supports two modes in which keys are managed: either just storing them in-memory while a container is running, or persisting them in a PostgresSQL database with Veramo SDK. Using an external Postgres database allows for "custodian" mode where identity and cheqd/Cosmos keys can be offloaded by client applications to be stored in the database.

By default, ENABLE_EXTERNAL_DB is set to off/false. To enable external Veramo KMS database, set ENABLE_EXTERNAL_DB to true, then define below environment variables in .env file:

1. EXTERNAL_DB_CONNECTION_URL: PostgreSQL database connection URL, e.g. postgres://<user>:<password>@<host>:<port>/<database>.
2. EXTERNAL_DB_ENCRYPTION_KEY: Secret key used to encrypt the Veramo key-specific database tables. This adds a layer of protection by not storing the database in plaintext.
3. EXTERNAL_DB_CERTIFICATE: Custom CA certificate required to connect to the database (optional).

API Authentication using LogTo

By default, the application has API authentication disabled (which can be changed in configuration). If, however, you'd like to run the app with API authentication features, the following variables need to be configured.

We use a self-hosted version of LogTo, which supports OpenID Connect. Theoretically, these values could also be replaced with LogTo Cloud or any other OpenID Connect identity provider.

By default, ENABLE_AUTHENTICATION is set to off/false. To enable external Veramo KMS database, set ENABLE_AUTHENTICATION to true, then define below environment variables in .env file:

1. Endpoints
   1. LOGTO_ENDPOINT: API endpoint for LogTo server
   2. LOGTO_DEFAULT_RESOURCE_URL: Root of API resources in this application to be guarded. (Default: http://localhost:3000/ on localhost.)
   3. LOGTO_MANAGEMENT_API: URL of management API for LogTo. This is typically static within self-hosted LogTo applications and is not meant to be a resolvable URL. (Default: https://default.logto.app/api)
2. User-facing APIs
   1. LOGTO_APP_ID: Application ID for the cheqd Studio application in LogTo. This can be set up as type "Traditional Web"
   2. LOGTO_APP_SECRET: Application secret associated with App ID above.
3. Machine-to-machine backend APIs
   1. LOGTO_M2M_APP_ID: Application ID for machine-to-machine application in LogTo. This is used for elevated management APIs within LogTo.
   2. LOGTO_M2M_APP_SECRET: Application secret
4. Default role update using LogTo webhooks: LogTo supports webhooks to fire of requests to an API when it detects certain actions/changes. If you want to automatically assign a role to users, a webhook is recommended to be setup for firing off whenever there's a new account created, or a new sign-in.
   1. LOGTO_DEFAULT_ROLE_ID: LogTo Role ID for the default role to put new users into.
   2. LOGTO_WEBHOOK_SECRET: Webhook secret to authenticate incoming webhook requests from LogTo.
5. Miscellaneous
   1. COOKIE_SECRET: Secret for cookie encryption.
   2. API_KEY_EXPIRATION (optional): Expiration time for API keys in days. (Default 30 days)

Faucet settings

This section describes bootstrapping things for newcomers accounts. If it's enabled cheqd Studio auto-populates some tokens on the testnet for making the process simpler.

1. ENABLE_ACCOUNT_TOPUP: Enable/disable such functionality (false by default)
2. FAUCET_URI: Faucet service API endpoint (Default: https://faucet-api.cheqd.network/credit)
3. TESTNET_INITIAL_TOPUP_CHEQ: Amount of testnet CHEQ a new account's testnet address is topped up to when it is bootstrapped (only if ENABLE_ACCOUNT_TOPUP is true, and only when the testnet account is newly created, not on later calls), converted to ncheq internally. The top-up is debited from the customer's monthly faucet quota (FAUCET_MONTHLY_LIMIT_CHEQ); if the quota is exhausted it is skipped and account creation still succeeds. The old name TESTNET_FAUCET_UPPER_CAP_CHEQ is no longer read, because it was the faucet cap and would inflate this amount. (Default: TESTNET_MINIMUM_BALANCE, so 10,000 CHEQ)
4. TESTNET_MINIMUM_BALANCE: Backward-compatible fallback for the initial top-up amount if TESTNET_INITIAL_TOPUP_CHEQ is not set. (Default: 10,000 CHEQ testnet tokens)
5. FAUCET_MONTHLY_LIMIT_CHEQ: The most CHEQ a customer can request through POST /account/faucet across all their addresses per calendar month (UTC). Usable with a Studio session or an API key. Requests that would exceed it return 429 with a Retry-After header. The initial top-up at account creation counts towards it. (Default: 100,000 CHEQ)
6. FAUCET_ADDRESS_CAP_CHEQ: The most CHEQ a single testnet address can hold before POST /account/faucet stops topping it up. (Default: FAUCET_MONTHLY_LIMIT_CHEQ, so there is one figure unless this is set) 6a. FAUCET_DEFAULT_REQUEST_CHEQ: The amount of CHEQ POST /account/faucet sends when the request has no amount, so one call with only an address does not use the whole monthly quota. It is lowered to the room under FAUCET_ADDRESS_CAP_CHEQ or the quota left if either is smaller. An explicit amount is not affected. (Default: 10,000 CHEQ)
7. FAUCET_SUBSCRIPTION_CACHE_SECONDS: How long POST /account/faucet caches a customer's Stripe subscription status and plan, so API-key use does not call Stripe on every request. The stored subscription status is still checked on every request, so a cancellation takes effect immediately; a plan change can take this long to be seen. 0 disables the cache. (Default: 60)
8. FAUCET_MIN_INTERVAL_SECONDS: Minimum gap between two POST /account/faucet requests from the same customer, so a script cannot hammer the endpoint in a tight loop. A request made too soon returns 429 with a Retry-After header and does not reach Stripe, the RPC node or the faucet. 0 disables it. Does not apply to the automatic top-up at account creation. (Default: 10)
9. FAUCET_PENDING_TIMEOUT_SECONDS: How long a faucet quota reservation that has not been confirmed counts towards the quota before it is treated as abandoned (for example because the process died before calling the faucet). Keep it longer than the longest faucet call. A reservation whose faucet call threw (outcome unknown, so tokens may have been sent) always keeps counting. (Default: 600)
10. FAUCET_BALANCE_SETTLE_SECONDS: A faucet transfer takes a few blocks to show up in an address's on-chain balance. For this many seconds, requests already made for the same address are subtracted from the room left under FAUCET_ADDRESS_CAP_CHEQ, so simultaneous requests cannot each be allowed the full room. (Default: 20)
11. FAUCET_REQUEST_RETENTION_MONTHS: How many calendar months of faucet request history to keep in the faucetRequest table. Only the current month is needed to enforce the quota; older rows are kept for support and deleted after this. The cleanup runs inside normal faucet requests, at most once an hour per process (Studio has no scheduler). 0 keeps everything. To clean up by hand: DELETE FROM "faucetRequest" WHERE "createdAt" < date_trunc('month', now() AT TIME ZONE 'UTC') - interval '13 months'; (Default: 13)
12. FAUCET_REQUEST_TIMEOUT_SECONDS: How long to wait for the faucet service to answer before giving up. A POST /account/faucet that times out returns 504; the faucet may still have credited the account, so the quota used is kept. (Default: 30)
13. FAUCET_API_KEY: API key for faucet service authentication
14. FAUCET_ACCESS_CLIENT_ID: Cloudflare Access client ID for accessing the Testnet Faucet API
15. FAUCET_ACCESS_CLIENT_SECRET: Cloudflare Access client secret for accessing the Testnet Faucet API

POST /account/faucet accepts three kinds of credential: a Studio user session (bearer token), an API key (x-api-key header) and a machine-to-machine token (bearer token plus a customer-id header selecting the customer). All three are checked against the same rule: the scopes they carry must include request:faucet:testnet. A user session and an API key get their scopes from the user's LogTo roles, so the scope comes with the Basic and Build plan roles; a machine-to-machine token carries its scopes in the token, so request:faucet:testnet must be granted to the M2M application's role in LogTo. The plan check, address ownership, quota and limits apply identically to all three.

The faucet quota, limits and handlers have two Postgres-backed test suites that are skipped unless FAUCET_TEST_DATABASE_URL points at a disposable database, so a plain npm run test:unit and CI are unaffected. Start a database with docker run -d --rm --name faucet-test-db -e POSTGRES_PASSWORD=pw -e POSTGRES_DB=studio -p 55432:5432 postgres:16, then:

• the ledger tests (jest): FAUCET_TEST_DATABASE_URL=postgres://postgres:pw@localhost:55432/studio npm run test:unit -- faucet-request.service
• the handler tests (Node's test runner, which needs Node 20 because the controller's dependencies do not load on newer versions): FAUCET_TEST_DATABASE_URL=postgres://postgres:pw@localhost:55432/studio npx -y -p node@20 node --import tsx --import ./tests/integration/hooks/register.mjs --test tests/integration/faucet-handler.test.ts

Faucet decisions are logged as one JSON line each, with an event name, so a blocked or refunded request can be traced: faucet.reserved, faucet.completed, faucet.released (the faucet reported a failure, quota given back), faucet.unknown (the faucet call threw, quota kept), faucet.quota_exceeded, faucet.too_frequent, faucet.address_cap_exceeded, faucet.reservations_abandoned, faucet.bootstrap_topup_skipped, faucet.retention_deleted and the *_failed errors. Rejections are warnings and carry the customer, address, amount and the relevant figures (usedNcheq, limitNcheq, roomNcheq, retryAfterSeconds); the early checks that run before Stripe are marked "stage":"precheck". A customer's history is also in the faucetRequest table: SELECT "createdAt", address, "amountNcheq", status FROM "faucetRequest" WHERE "customerId" = '<id>' ORDER BY "createdAt" DESC;.

Studio exposes POST /account/faucet for authenticated Studio users on Basic-or-higher subscriptions. The endpoint accepts optional address and amount fields; amount is expressed in CHEQ. If address is omitted, Studio uses the customer's testnet payment account. If amount is omitted, Studio sends FAUCET_DEFAULT_REQUEST_CHEQ (10,000 CHEQ by default), or less if the room under FAUCET_ADDRESS_CAP_CHEQ or the monthly quota left is lower; pass amount to request more. Requests that exceed the address cap return a requestMore.mailtoHref for contacting product@cheqd.io.

Account balances & CHEQ pricing

GET /account/balances (read:account scope) returns the on-chain balance of the authenticated customer's mainnet and testnet payment accounts in ncheq, CHEQ and USD. The CHEQ/USD rate is fetched from CoinGecko and cached in-process. The endpoint degrades gracefully: if the rate lookup or a network's RPC endpoint is unavailable it still returns 200, with the affected usd / rate / balance fields set to null.

1. COINGECKO_API_URL: CoinGecko API base URL (Default: https://api.coingecko.com/api/v3). Set to a pro-api.coingecko.com URL to use a Pro key.
2. COINGECKO_TOKEN_ID: CoinGecko coin id for CHEQ (Default: cheqd-network).
3. COINGECKO_API_KEY (optional): CoinGecko API key. Sent as x-cg-demo-api-key, or x-cg-pro-api-key when COINGECKO_API_URL points at the Pro API.
4. CHEQ_USD_RATE_CACHE_TTL (optional): seconds to cache the CHEQ/USD rate for (Default: 300).

Stripe integration

The application supports Stripe integration for payment processing.

1. STRIPE_ENABLED - Enable/disable Stripe integration (false by default)
2. STRIPE_SECRET_KEY - Secret key for Stripe API. Please, keep it secret on deploying
3. STRIPE_PUBLISHABLE_KEY - Publishable key for Stripe API.
4. STRIPE_WEBHOOK_SECRET - Secret for Stripe Webhook.
5. STRIPE_BUILD_PLAN_ID - Subscription product ID of the Build plan
6. STRIPE_BASIC_PLAN_ID - Subscription product ID of the Basic plan. This replaces the former Explorer/Test plan.
7. STRIPE_TEST_PLAN_ID - Backward-compatible fallback product ID for the former Test/Explorer plan. Keep for one release while migrating to STRIPE_BASIC_PLAN_ID.

When a new Studio customer is created with Stripe enabled, Studio creates a Stripe customer and starts the Basic plan as a 30-day trial subscription. This makes the customer immediately trialing for subscription checks without requiring a payment method at signup.

3rd Party Connectors

The app supports 3rd party connectors for credential storage and delivery.

Verida

The app's Verida Network connector can be enabled to deliver generated credentials to Verida Wallet.

By default, ENABLE_VERIDA_CONNECTOR is set to off/false. To enable external Veramo KMS database, set ENABLE_VERIDA_CONNECTOR to true, then define below environment variables in .env file:

1. VERIDA_PRIVATE_KEY: Secret key for Verida Network API.
2. POLYGON_PRIVATE_KEY: Secret key for Polygon Network.

🧑‍💻🛠 Developer Guide

Run as standalone application using Docker Compose

If you want to run the application without any external databases or dependent services, we provide a Docker Compose file to spin up a standalone service.

docker compose -f docker/no-external-db/docker-compose-no-db.yml up --detach

This standalone service uses an in-memory database with no persistence, and therefore is recommended only if you're managing key/secret storage separately.

The no-db.env file in the same folder contains all the environment variables necessary to configure the service. (See section Configuration above.)

Run with external Key Management System (KMS) and/or authentication service using Docker Compose

Construct the postgres URL and configure the env variables mentioned above.

Spinning up a Docker container from the pre-built studio Docker image on Github is as simple as the command below:

Configure PostgreSQL database

Configure the environment variables in the postgres.env file:

1. POSTGRES_USER: Username for Postgres database
2. POSTGRES_PASSWORD: Password for Postgres database
3. POSTGRES_MULTIPLE_DATABASES: Database names for multiple databases in the same cluster, e.g.: "app,logto". This sets up multiple databases in the same cluster, which can be used independently for External Veramo KMS or LogTo service.

Then, make the Postgres initialisation scripts executable:

chmod +x docker/with-external-db/pg-init-scripts/create-multiple-postgresql-databases.sh

Start LogTo service

Configure the environment variables in the logto.env file with the settings described in section above.

Then, run the LogTo service to configure the LogTo application API resources, applications, sign-in experiences, roles etc using Docker Compose:

docker compose -f docker/with-external-db/docker-compose-with-db.yml --profile logto up --detach

Configuring LogTo is outside the scope of this guide, and we recommend reading LogTo documentation to familiarise yourself.

Start studio app

Configure the environment variables in the with-db.env file with the settings described in section above. Depending on whether you are using external Veramo KMS only, LogTo only, or both you will need to have previously provisioned these services as there are environment variables in this file that originate from Postgres/LogTo.

Then, start the service using Docker Compose:

docker compose -f docker/with-external-db/docker-compose-with-db.yml up --detach

Running app or LogTo migrations

When upgrading either the external Veramo KMS or LogTo, you might need to run migrations for the underlying databases.

You can run just the migration scripts using Docker Compose profiles defined in the Compose file.

For example, to run cheqd Studio app migrations on an existing Postgres database (for external Veramo KMS):

docker compose -f docker/with-external-db/docker-compose-with-db.yml --profile app-setup up --detach

Or to run LogTo migrations on an existing Postgres database:

docker compose -f docker/with-external-db/docker-compose-with-db.yml --profile logto-setup up --detach

Build using Docker

To build your own image using Docker, use the Dockerfile provided.

docker build --file docker/Dockerfile --target runner . --tag studio:local

🐞 Bug reports & 🤔 feature requests

If you notice anything not behaving how you expected, or would like to make a suggestion / request for a new feature, please create a new issue and let us know.

💬 Community

Our Discord server is our primary chat channel for the open-source community, software developers, and node operators.

Please reach out to us there for discussions, help, and feedback on the project.

🙋 Find us elsewhere