> For the complete documentation index, see [llms.txt](https://docs.empe.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.empe.io/develop/issuer/terminology-and-concepts.md). # Terminology and Concepts This glossary defines the terms used throughout the Issuer Service documentation. The Issuer Service exposes its capabilities over an HTTP API and stores its data in PostgreSQL. Operator endpoints require a valid OIDC JWT Bearer token (see **Authentication** below). **Self-Sovereign Identity (SSI)** A user-centric approach to digital identity that lets individuals and organizations control their own identifiers and credentials without relying on a central authority. **Decentralized Identifier (DID)** A globally unique identifier for an entity (such as an issuer, verifier, or holder). The Issuer Service supports two DID methods: * **`did:web`** — resolved over HTTPS. The service hosts the DID document itself and serves it at `/{uuid}/did.json` (also available at `/{uuid}/.well-known/did.json`). A `did:web` looks like `did:web:issuer.example.com:`. * **`did:key`** — self-contained; the public key is encoded directly in the identifier, so no network lookup is needed. A `did:key` looks like `did:key:z6Mk...`. Both methods use Ed25519 keys. `did:jwk` identifiers are also resolvable. **DID Document** A JSON document, resolvable from a DID, that contains the public keys and verification methods needed to verify signatures produced by the DID's controller. **EMPE DID Method and EMPE Blockchain** The `did:empe` method and the EMPE blockchain form the trust layer of the wider Empeiria ecosystem. The Issuer Service works with `did:web` and `did:key` identifiers, which it creates and serves itself over HTTPS; `did:empe` and the blockchain are separate parts of the ecosystem and are not required to run this service. **Verifiable Credential (VC)** A cryptographically signed credential that attests to attributes of a subject. VCs follow W3C standards, ensuring integrity and authenticity. The Issuer Service issues two credential formats: SD-JWT VC and JWT-VC-JSON. **SD-JWT VC** A Verifiable Credential encoded as a Selective Disclosure JWT (`vc+sd-jwt` / `sd-jwt-vc`). Each SD-JWT VC carries a `vct` (Verifiable Credential Type) and supports selective disclosure of individual claims. **JWT-VC-JSON** A Verifiable Credential encoded as a standard JWT (`jwt-vc-json` / `jwt_vc_json`), typed with one or more credential types (for example `["VerifiableCredential", "EmploymentCredential"]`). **Selective Disclosure** A property of SD-JWT VCs that lets a holder reveal only a chosen subset of claims to a verifier while keeping the rest hidden, without breaking the issuer's signature. The claims that may be disclosed are defined by the schema's disclosure frame (for example `["employee_id", "full_name", "department"]`). **Credential Schema** A JSON-based template that defines the structure, properties, and required fields of a credential type. A schema is identified by a `name` and `version` (token-like values matching `^[A-Za-z0-9][A-Za-z0-9._-]*$`, no spaces) and contains a JSON Schema describing the claims. Schemas are versioned so credential definitions can evolve. For example, a schema named `EmployeeBadge` at version `1.0` requires `employee_id`, `full_name`, and `department`. **Credential Configuration** The combination of a schema version and a credential format, identified as `Name@Version:format` — for example `EmployeeBadge@1.0:sd-jwt`. A schema that supports both formats yields two credential configurations (`...:sd-jwt` and `...:jwt-vc-json`). Credential offers reference credentials by their credential configuration id. **OpenID4VCI (OpenID for Verifiable Credential Issuance)** The standards-based protocol the Issuer Service uses to deliver credentials to wallets. The service implements the pre-authorized code flow with an optional PIN. **Credential Offer** An invitation, created by the issuer, for a wallet to claim one or more credentials. An offer references one or more credential configuration ids and is delivered as an `openid-credential-offer://` URI (returned as `credentialOfferUri`) or as a QR-code PNG. **Pre-Authorized Code Flow** The OpenID4VCI flow used for issuance. The issuer mints a credential offer that already contains a pre-authorized code, so the wallet can claim the credential without a separate interactive login. Set `requirePin: true` on the offer to additionally require a PIN. **PIN (Transaction Code)** An out-of-band code that the holder must enter to claim a credential when `requirePin` is set. When a PIN is required, it is returned as `userPin` in the offer response and as the `X-Pin` header on the QR-code response. **Issuance Metadata** Optional data attached to a credential offer that supplies the claim values for each credential configuration. It is passed as `issuanceMetadata` on the offer, typically as `{ "claimsByConfigurationId": { "EmployeeBadge@1.0:sd-jwt": { "employee_id": "EMP-001", "full_name": "Ada Lovelace", "department": "Engineering" } } }`. **Issuance Session** A server-side record that tracks the state of a single credential offer from creation through claiming. Each offer returns an `issuanceSessionId`; sessions can be listed per issuer and inspected individually, including a regenerable QR code for the offer URI. **Issuer** A registered entity, bound to an existing DID, that signs and issues credentials. An issuer is created from a DID, can have one or more schemas assigned to it, and serves its own OpenID4VCI issuer metadata document (the issuer's `.well-known/did-configuration`). **Direct Credential Signing** A flow that signs a credential directly, without the wallet/offer cycle. The caller supplies a `format` (`sd-jwt-vc` or `jwt_vc_json`), a claims `payload` (including `vct` for SD-JWT), an optional `subjectDid`, and an optional `disclosureFrame` for SD-JWT. The service returns the signed credential and its format. **Holder (Cloud Wallet)** A wallet hosted and managed by the service on behalf of a single user. A holder can claim offered credentials and present them to verifiers. Ownership is enforced, so each user can access only their own holders. **One-Click Deployment Portal** A provisioning tool that deploys an Issuer Service instance and its operator admin panel, then helps with initial configuration. It provisions the running service; DID and issuer creation are explicit admin API calls made after deployment. **Authentication** Operator endpoints are protected by OIDC JWT Bearer tokens validated against a JWKS endpoint. Each request must include an `Authorization: Bearer ` header. The agent/DID and holder (wallet) routes additionally require the `admin` role in the token's `realm_access.roles` or in a `resource_access` client-role entry; the schema, credential-offer, issuance-session, and signing endpoints require a valid token but no specific role (see [Authentication](/develop/issuer.md#authentication)). --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.empe.io/develop/issuer/terminology-and-concepts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.