Skip to content
/ studio Public

API server for interacting with decentralised identity functionality on the cheqd Network

License

Notifications You must be signed in to change notification settings

cheqd/studio

Repository files navigation

Credential Service

GitHub release (latest by date) GitHub Release Date GitHub license

GitHub release (latest by date including pre-releases) GitHub commits since latest release (by date) GitHub contributors

GitHub Workflow Status GitHub Workflow Status GitHub repo size

ℹ️ Overview

The purpose of this service is to issue and verify credentials. This service by itself does not take care of storing the credentials. If you'd like to store credentials, you would have to pair this service with secret-box-service. This service is also dependent on auth0-service

📖 Endpoints

Issue a credential

  • Endpoint POST /credentials/issue
  • Accepts: application/json
  • Request Body: JSON object with following fields
    • attributes - A json object with all the credential attributes
    • subjectDid - DID of the holder of the credential
    • type - A string representation of the credential type e.g. "PERSON" (optional)
    • @context - context of the issued credential (optional)
    • expirationDate - Date of expiration of the JWT (optional)
  • Success Response Code: 200
  • Invalid Request Response Code - 400
  • Internal Error Response Code - 500

Verify a Credential

  • Endpoint POST /credentials/verify
  • Accepts: application/json
  • Request Body: JSON object with following fields:
    • credential - A verifiable credential or the JWT string
  • Success Response Code - 200
  • Invalid Request Response Code:
    • 400: Bad request body
    • 405: Wrong content type
  • Internal Error Response Code - 500

Health Check

  • Endpoint: / (This endpoint redirects to the swagger api docs)

🔧 Configuration

The application allows configuring the following parameters using environment variables.

Core configuration

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. (https://rpc.cheqd.network:443)
  3. RESOLVER_URL: API endpoint for a DID Resolver endpoint that supports did:cheqd.
  4. APPLICATION_BASE_URL: URL of the application (external domain name)

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.

  1. DB_CONNECTION_URL: Postgres database connection URL, e.g. postgres://<user>:<password>@<host>:<port>/<database>
  2. 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. 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.

  1. ENABLE_AUTHENTICATION: Turns API authentication guards on/off. (Default: false)
  2. LOGTO_ENDPOINT: API endpoint for LogTo server
  3. LOGTO_RESOURCE_URL: API resource associated with application
  4. LOGTO_APP_ID: Application ID from LogTo. For now, Application is supposed to be a TraditionalWeb
  5. LOGTO_APP_SECRET: Application secret. Also should encrypted in deployment
  6. ALLOWED_ORIGINS: CORS allowed origins used in the app
  7. DEFAULT_CUSTOMER_ID: Customer/user in LogTo to use for unauthenticated users
  8. ALL_SCOPES: List of all scopes. Should be a string with scopes divided by whitespace, like account:create account:read did:create
  9. COOKIE_SECRET: Secret for cookie encryption.

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.

  1. ENABLE_VERIDA_CONNECTOR: Turns Verida connector on/off. (Default: false)
  2. VERIDA_NETWORK: Verida Network type to connect to. (Default: testnet)
  3. VERIDA_PRIVATE_KEY: Secret key for Verida Network API.
  4. POLYGON_RPC_URL: Polygon Network RPC URL for connections.
  5. POLYGON_PRIVATE_KEY: Secret key for Polygon Network.

Run the application

Initiate a Postgres database, in case you're using an external database.

docker pull postgres
docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d postgres

Construct the postgres url and configure the env variables mentioned above

Once configured, the app can be run using NPM:

npm start

🧑‍💻🛠 Developer Guide

Build using NPM

Dependencies can be installed using NPM or any other node package manager.

npm install
npm run build

Build using Docker

To build and run in Docker, use the Dockerfile provided.

docker build -t credential-service .

🐞 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

The cheqd Community Slack 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

Telegram Discord Twitter LinkedIn Slack Medium YouTube