Skip to content
You are reading Codefi Orchestrate development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.


Authentication restricts access to resources in a multi-tenant environment.

Machine to Machine

Machine to machine authentication uses the AUTH_API_KEY environment variable to enable internal communication between Orchestrate microservices. All running microservices from the same Orchestrate instance must be given the same key when they are started or restarted.


Ensure the value of AUTH_API_KEY is not inferable by the client. We recommend generating a strong secret.

Ensure the value of the secret cannot leak and is not used for client to server authentication. Having the AUTH_API_KEY value enables full access to the entire data stack in the Orchestrate instance.

Client to Server

Client to server authentication is based on OpenID-Connect. Three parties are involved:

  • Client

    User or external app sending a request to Orchestrate.

  • Server

    Orchestrate microservice receiving a request.

  • Identity provider

    Third-party compatible with OpenID-Connect. The identity provider generates and signs the JWT token. Typically, Auth0.

Authentication occurs in two steps:

  1. The client authenticates to the identity provider (for example, Auth0). A JWT token is returned to the client. The JWT token can be used for multiple requests until the token expires.
  2. The client passes the JWT token to Orchestrate in the authorization request header. A JWT token is checked and access to the authenticated tenant is allowed.


The Prometheus HTTP endpoints for metrics (by default, on port 8082) are not protected by authentication. To hide the metrics endpoint externally, do not expose the endpoint when configuring the ingress to your Kubernetes cluster. The Orchestrate Helm charts have an example.

Custom Claims Format

An example JWT for Orchestrate multi-tenancy is displayed below.


The custom part of the claim is the namespace defined by the AUTH_JWT_CLAIMS_NAMESPACE environment variable and the tenant_id.

The tenant ID is specified only in the JWT and is set by the identity provider (for example, Auth0). That is, the tenant ID is not configured in Orchestrate. When you enable multi-tenancy, all requests require an authorization token so resources (accounts, chains, and contracts) are associated with a tenant ID on creation. Authenticated requests return only resources linked to the tenant ID.

Configure authentication by setting the relevant environment variables.

ConsenSys has acquired Quorum from J.P. Morgan. Please read the FAQ.
Questions or feedback? You can obtain paid professional support by Consensys at