The `did:genuinein` Method Specification

Version: 1.0

Status: Draft

1. Abstract

The did:genuinein method is a specific implementation of the W3C Decentralized Identifiers (DIDs) v1.0 specification. It is designed to create and manage DIDs that are anchored to the GenuineIN identity platform. This method provides a centralized, yet cryptographically verifiable, approach to digital identity, enabling individuals and organizations to have a persistent, resolvable identifier for issuing and presenting Verifiable Credentials. The resolution of did:genuinein identifiers is performed via a trusted, public RESTful API, ensuring ease of use and integration for developers.

2. Method-Specific Identifier (MSI) Syntax

The syntax follows:

did:genuinein:<record-type>[:<role-type>]:<unique-identifier>

Where:

<record-type> defines the domain of the record (e.g., education, certification).
<role-type> (optional) defines the entity's role (ler, issuer, receiver).
<unique-identifier> is a Base64URL-encoded, opaque identifier.

Supported Record Types (15)

Type	Description
ler	Learner Employment Record holder (individual)
issuer	Authorized issuing institution
receiver	Verifier or relying party (e.g., employer)
education	Educational records (degrees, courses)
experience	Employment history
course	Learning course completion
certification	Certifications and licenses
internship	Internship records
training	Completed training programs
participation	Participation in events or activities
project-participation	Project-based contributions
research	Research activities
testscore	Assessment or test scores
recognition	Awards or recognitions
paper-publication	Research and publications
volunteer	Volunteer activities
sports-participation	Sports participation records
membership	Memberships in organizations

Example DIDs:

did:genuinein:education:ler:zR9iC3tX-7b8E2fG_JkLpQ
did:genuinein:experience:issuer:aB8hD2sY-6c7F1eH_KjLpQ
did:genuinein:project:receiver:xP5kF9vU-2a1B9gI_MnQrS

3. CRUD Operation Definitions

All Create, Read, Update, and Deactivate (CRUD) operations for the DID itself are managed through the official GenuineIN DID API.

Base Endpoint: https://api.genuinein.com/v1/dids/

3.1 Create (Register)

A new did:genuinein is created when a user, authenticated on the GenuineIN platform, initiates a registration request.

Endpoint: POST /v1/dids/

Request Body: A JSON object containing the desired didType and the initial public key.

{
  "didType": "ler",
  "publicKeyJwk": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOy-V24_1F2yBc"
  }
}

Result: The server registers the DID and returns the full DID Document.

3.2 Read (Resolve)

Resolving a did:genuinein is a public and unauthenticated operation.

Endpoint: GET /v1/dids/{did-type}:{unique-identifier}

Result: The server returns a 200 OK response with a JSON object containing the DID Document. A DID Document for an issuer may include a `service` endpoint pointing to the credential API.

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:genuinein:issuer:aB8hD2sY-6c7F1eH_KjLpQ-def456uvw",
  "authentication": [...],
  "service": [
    {
      "id": "#credentials",
      "type": "CredentialService",
      "serviceEndpoint": "https://genuinein.com/api/credentials/"
    }
  ]
}

3.3 Update

The controller of a DID can update its associated DID Document.

Endpoint: PUT /v1/dids/{did-type}:{unique-identifier}
Authentication: The request must include a digital signature created by a key in the current document's authentication method.
Result: The server validates the signature and replaces the DID Document.

3.4 Deactivate (Revoke)

The controller of a DID can permanently deactivate it.

Endpoint: DELETE /v1/dids/{did-type}:{unique-identifier}
Authentication: Requires a digital signature, identical to the Update operation.
Result: The server marks the DID as deactivated. Future resolution attempts will result in a 410 Gone status.

4. Security Considerations

Transport Layer Security: All API endpoints must be secured using TLS 1.2 or higher.
Authentication: State-changing operations are protected by cryptographic signatures.
Key Management: The security of the DID relies on the controller's ability to securely manage their private keys.

5. Privacy Considerations

Identifier Opacity: The unique-identifier is opaque and does not contain personal data.
Data Minimization: The DID Document itself should only contain public keys and service endpoints.
Selective Disclosure: The primary privacy benefit comes from using the DID to present Verifiable Credentials, which support selective disclosure.

6. Associated Services

The following endpoints are not part of the DID resolution process itself but are services that a did:genuinein DID Document may point to via its serviceEndpoint. They are used for handling Verifiable Credentials (VCs).

6.1 Verifiable Credential Retrieval

This endpoint allows for the retrieval of a specific Verifiable Credential's data.

Endpoint: GET /api/credentials/{credentialId}
Logic: The service uses the credentialId (GRID) to determine the credential type via its `pecid` substring. It then routes the request to the appropriate internal repository (e.g., `educationRepo`, `experienceRepo`) to fetch the specific LER data and return it as a JSON object.

6.2 Credential Status Check

This endpoint allows for checking the revocation status of a Verifiable Credential.

Endpoint: GET /api/credentials/status/{grid}
Logic: The service takes a credential's GRID, validates it, and returns a status object conforming to the `CredentialStatusList2021` specification. The status can be `active`, `revoked`, or `suspended` based on the record's state in the GenuineIN system.

Example Response Body:

{
  "id": "https://genuinein.com/credentials/status/...",
  "type": "CredentialStatusList2021",
  "statusPurpose": "revocation",
  "status": "active",
  "updated": "2025-07-09T04:27:00Z"
}

The did:genuinein Method Specification