> For the complete documentation index, see [llms.txt](https://docs.toolkit.equs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolkit.equs.ai/standards/issuance/configuration-issuer-and-vc-schema.md). # Configuration: Issuer and VC Schema Set up the Issuer that signs your credentials and the VC Schema that defines them Before your first Issuance you configure two things: an **Issuer**, the entity that signs credentials, and a **VC Schema**, which defines what a credential of a given type contains. Both are set up once and reused by every flow. Setting them up also creates two things behind the scenes: your **Issuer Key**, generated inside the platform's KMS, and the **Revocation Registry** that will back every credential you issue. Neither needs configuring, and neither holds personal data. {% code collapsedlinecount="10" %} ```mermaid flowchart LR T["Your Tenant"] --> I1["Issuer A
did:web"] T --> I2["Issuer B
did:web"] I1 --- S1["VC Schema
'Membership'
v1 · v2"] I2 --- S1 I2 --- S2["VC Schema
'Age check'
v1"] style T fill:#e8f0fe,stroke:#4285f4 style I1 fill:#fff4e5,stroke:#f9ab00 style I2 fill:#fff4e5,stroke:#f9ab00 ``` {% endcode %} The relationship is many-to-many. A Schema names the Issuers allowed to issue it, so one Schema can be shared across Issuers and one Issuer can carry many Schemas. Separate Issuers are how you separate credential programs, brands, or environments. You can do all of this with no code in the [Operator Portal](https://portal.us.equs.ai/), or through the REST API. Each section below covers both. In the portal, open **Issuance** and select the caret (**∨**) on the **Issue VC** button: there you can manage Issuers and VC Schemas. To get access to the portal, see [Registration](/standards/onboarding/registration.md). ### Create the Issuer An Issuer is identified by a `did:web` anchored to a domain the platform controls. Verifiers resolve that DID to check who signed a credential, which is why the Issuer - not your Tenant - is the identity that appears to the outside world. Its display name and logo are what the Holder sees in their wallet, so treat them as public-facing brand, not internal labels. Issuer names must be unique within your Tenant, and the number of Issuers you can create is [capped](/standards/api/rate-limits.md). Issuers can also be updated, deactivated, and reactivated. A deactivated Issuer cannot be named in a new Schema - so deactivating one is how you retire a credential program without deleting its history. #### In the Operator Portal Add an Issuer with: * **Name** - required, and unique within your Tenant. This is the name Holders see in their wallet. * **Logo URL** - optional. A link to an image you host; there is no file upload. Without a logo, the Issuer is shown with the first letter of its name. * **DID method** - `did:web`, currently the only option. The DID itself is generated and hosted for you, so there is nothing to publish on your side. From the list you can edit an Issuer, or deactivate and reactivate it.
#### With the API {% hint style="info" icon="rectangle-api" %} All calls mentioned on this page are on the [Control API](https://docs.toolkit.equs.ai/standards/issuance/pages/MvAvsnLQU3ER2hOIIDU2#id-2.4.1-apis). {% endhint %} ## Create Issuer > Create new Issuer ```json {"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Issuer","description":""}],"security":[{"sp":[]},{"tenant":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."},"tenant":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant. Token of a Tenant machine client or of a Tenant portal user, carrying the `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"CreateIssuerRequest":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the issuer."},"logo":{"description":"Logo displayed for this Issuer when presenting issued credentials.","allOf":[{"$ref":"#/components/schemas/Logo"}]},"didMethod":{"type":"string","description":"DID method used to generate the DID for this issuer.","enum":["did:web"]},"batchSize":{"type":"number","minimum":1,"maximum":100,"default":1,"description":"How many Credentials a Wallet may request in one Credential Request. 1 disables batch issuance. Any greater value enables it at that size."}},"required":["name","didMethod"]},"Logo":{"type":"object","properties":{"uri":{"type":"string","format":"uri","description":"Publicly accessible URL of the logo image."},"altText":{"type":"string","description":"Alternative text describing the logo, used for accessibility."}},"required":["uri"]},"CreateIssuerResponse":{"type":"object","properties":{"id":{"type":"string","description":"Issuer unique ID"}},"required":["id"]}}},"paths":{"/api/v1/issuers":{"post":{"description":"Create new Issuer","operationId":"IssuerController_createIssuer_api/v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIssuerRequest"}}}},"responses":{"201":{"description":"When Issuer is created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIssuerResponse"}}}},"400":{"description":"When the issuer name already exists."},"409":{"description":"When the Tenant already owns its maximum number of Issuers."}},"summary":"Create Issuer","tags":["Issuer"]}}}} ``` ### Create the VC Schema A Schema defines the structure and claims of one credential type. You don't have to start from scratch. EQUS curates a set of **Schema Templates**, browsable by category, that you can use as a base for a common credential type. A template is only a starting point: it never constrains what you can issue, and you can change anything in it. #### In the Operator Portal A new Schema takes three steps: {% stepper %} {% step %} #### Choose a starting point Pick one of the Schema Templates to pre-fill the editor with its details and claims, or **Custom Schema** to start from a blank one.
{% endstep %} {% step %} #### Configure the Schema * **Issuer** - required. Pick one of your Issuers, or create one with the **＋** beside the field. * **Name** - required. * **Description** - optional. * **Expiration in days** - optional. How long a credential stays valid after issuance; the API takes the same value in seconds. * **Branding** - background and text colors, and an optional logo with alt text, with a live preview of the credential card. The card shows the Issuer's logo as well. Custom colors are applied in EQUS wallets; other wallets may ignore them.
{% endstep %} {% step %} #### Define the Claims For each one, set: * **Name** - the label, such as *Full Name*. * **Path** - where the value sits in the credential. It is derived from the name; edit it to nest claims. * **Data type** - Text, Integer, Decimal, Boolean, Date, Time, DateTime or Array. * **Mandatory** - checked by default.
{% endstep %} {% endstepper %} In the portal, this is the only place a credential's structure is set. When you issue, the claims are fixed by the Schema and you supply values only. #### With the API ## Create VC Schema > Create new VC Schema ```json {"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Issuer","description":""}],"security":[{"sp":[]},{"tenant":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."},"tenant":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant. Token of a Tenant machine client or of a Tenant portal user, carrying the `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"CreateVcSchemaRequest":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the VC schema."},"description":{"type":"string","description":"Human-readable description of the VC schema."},"logo":{"description":"Logo displayed for credentials issued under this schema.","allOf":[{"$ref":"#/components/schemas/Logo"}]},"bgColor":{"type":"string","description":"Background color used when rendering the credential."},"textColor":{"type":"string","description":"Text color used when rendering the credential."},"format":{"type":"string","description":"Credential format used for VC schema.","enum":["SdJwtVc"]},"bindMethod":{"type":"array","description":"Cryptographic binding methods supported for holder key binding.","items":{"type":"string","enum":["JWK"]}},"credSignAlgs":{"type":"array","description":"Algorithm to sign credentials.","items":{"type":"string","enum":["EdDSA","ES256"]}},"proofSignAlgs":{"type":"array","description":"Algorithm for proof.","items":{"type":"string","enum":["EdDSA","ES256"]}},"expiration":{"type":"number","description":"Number of seconds after issuance until the credential expires."},"assurance":{"type":"string","description":"Level of assurance required for the credential subject data.","enum":["low","high"],"default":"low"},"public":{"type":"boolean","description":"Determines whether or not VC Schema can be used for VP flow by other tenants.","default":false},"claimDefs":{"description":"Claim definitions describing the schema of the credential.","type":"array","items":{"$ref":"#/components/schemas/VcSchemaClaimDefs"}},"issuers":{"description":"Identifiers of the issuers allowed to issue credentials of this schema.","type":"array","items":{"type":"string"}},"dedicatedDid":{"type":"string","description":"Dedicated DID type used to bind credentials of this schema.","enum":["KycDid"]}},"required":["name","format","bindMethod","credSignAlgs","proofSignAlgs","claimDefs","issuers"]},"Logo":{"type":"object","properties":{"uri":{"type":"string","format":"uri","description":"Publicly accessible URL of the logo image."},"altText":{"type":"string","description":"Alternative text describing the logo, used for accessibility."}},"required":["uri"]},"VcSchemaClaimDefs":{"type":"object","properties":{"path":{"minItems":1,"description":"Path segments identifying the claim within the credential subject.","type":"array","items":{"type":"string","maxLength":100,"minLength":1}},"name":{"type":"string","maxLength":100,"description":"Human-readable display name of the claim."},"dataType":{"enum":["Text","Decimal","Integer","Boolean","DateTime","Date","Time","Array","Display"],"type":"string","description":"Data type of the claim value. Defaults to Text, or to Display when the claim has nested claims."},"mandatory":{"type":"boolean","default":true,"description":"Indicates whether the claim must always be included when issuing a credential."}},"required":["path","name"]},"CreateVcSchemaResponse":{"type":"object","properties":{"id":{"type":"string","description":"VC schema unique ID"},"vcSchemaVersionId":{"type":"string","description":"VC schema version unique ID"}},"required":["id","vcSchemaVersionId"]}}},"paths":{"/api/v1/vc-schemas":{"post":{"description":"Create new VC Schema","operationId":"VcSchemaController_createVcSchema_api/v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVcSchemaRequest"}}}},"responses":{"201":{"description":"When VC Schema is created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVcSchemaResponse"}}}},"400":{"description":"- When one or more Issuer IDs do not exist.\n- When one or more Issuers are inactive.\n- When the VC Schema name already exists."}},"summary":"Create VC Schema","tags":["Issuer"]}}}} ``` To start from a template instead of a blank request, get the list of templates: ## Get VC Schema Templates > Get the paginated list of EQUS-curated VC Schema Templates, optionally filtered by category. A template is a starting point for creating a VC Schema, never a constraint on what may be issued. ```json {"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Issuer","description":""}],"security":[{"sp":[]},{"tenant":[]},{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."},"tenant":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant. Token of a Tenant machine client or of a Tenant portal user, carrying the `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"GetVcSchemaTemplatesResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/VcSchemaTemplateResponseItem"}},"pagination":{"$ref":"#/components/schemas/PaginationData"}},"required":["items","pagination"]},"VcSchemaTemplateResponseItem":{"type":"object","properties":{"id":{"type":"string","description":"VC Schema Template unique ID"},"version":{"type":"number","description":"Version of the credential shape this template represents."},"category":{"type":"string","description":"Registry category grouping related templates, such as identity or AML."},"name":{"type":"string","description":"Default display name, which the operator may change before creating a VC Schema."},"description":{"type":"string","description":"Human-readable description of the credential shape."},"format":{"type":"string","description":"Credential format the template is defined for.","enum":["SdJwtVc"]},"bindMethod":{"type":"array","description":"Cryptographic binding methods supported for holder key binding.","items":{"type":"string","enum":["JWK"]}},"credSignAlgs":{"type":"array","description":"Algorithms the credential may be signed with.","items":{"type":"string","enum":["EdDSA","ES256"]}},"proofSignAlgs":{"type":"array","description":"Algorithms the holder proof may be signed with.","items":{"type":"string","enum":["EdDSA","ES256"]}},"claimDefs":{"description":"Claim definitions describing the credential the template produces.","type":"array","items":{"$ref":"#/components/schemas/VcSchemaClaimDefs"}},"expiration":{"type":"number","description":"Number of seconds after issuance until the credential expires."},"assurance":{"type":"string","description":"Level of assurance required for the credential subject data.","enum":["low","high"]},"logo":{"description":"Logo displayed for credentials issued under this template.","allOf":[{"$ref":"#/components/schemas/Logo"}]},"bgColor":{"type":"string","description":"Background color used when rendering the credential."},"textColor":{"type":"string","description":"Text color used when rendering the credential."}},"required":["id","version","category","name","description","format","bindMethod","credSignAlgs","proofSignAlgs","claimDefs"]},"VcSchemaClaimDefs":{"type":"object","properties":{"path":{"minItems":1,"description":"Path segments identifying the claim within the credential subject.","type":"array","items":{"type":"string","maxLength":100,"minLength":1}},"name":{"type":"string","maxLength":100,"description":"Human-readable display name of the claim."},"dataType":{"enum":["Text","Decimal","Integer","Boolean","DateTime","Date","Time","Array","Display"],"type":"string","description":"Data type of the claim value. Defaults to Text, or to Display when the claim has nested claims."},"mandatory":{"type":"boolean","default":true,"description":"Indicates whether the claim must always be included when issuing a credential."}},"required":["path","name"]},"Logo":{"type":"object","properties":{"uri":{"type":"string","format":"uri","description":"Publicly accessible URL of the logo image."},"altText":{"type":"string","description":"Alternative text describing the logo, used for accessibility."}},"required":["uri"]},"PaginationData":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"}},"required":["page","limit"]}}},"paths":{"/api/v1/vc-schema-templates":{"get":{"description":"Get the paginated list of EQUS-curated VC Schema Templates, optionally filtered by category. A template is a starting point for creating a VC Schema, never a constraint on what may be issued.","operationId":"VcSchemaTemplateController_getVcSchemaTemplates_api/v1","parameters":[{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"default":10,"type":"number"}},{"name":"category","required":false,"in":"query","description":"Registry category to filter the templates by.","schema":{"type":"string"}}],"responses":{"200":{"description":"When VC Schema Templates are retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVcSchemaTemplatesResponse"}}}},"503":{"description":"When the template capability is disabled, or the registry cannot be retrieved and no cached copy is held."}},"summary":"Get VC Schema Templates","tags":["Issuer"]}}}} ``` --- # 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://docs.toolkit.equs.ai/standards/issuance/configuration-issuer-and-vc-schema.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.