API Specs for DIDroom Solution Components

Introduction

This document outlines the API specifications for the DIDroom solution components. It covers the Authorization Server, Credential Issuer, DIDroom Backend, and W3C-DID Federated Service. Each component has specific functionalities, endpoints, and parameters.

🪪 Credential Issuer

The Credential Issuer component handles the analysis, verification, and issuance of verifiable credentials. It also manages offers for credentials. Below are the details:

/credential

Description: Issues a single verifiable credential or transaction ID, preparing the corresponding credential response.
Endpoint: /credential
HTTP Method: POST
Parameters:

Parameter	Type	Description
format	string	REQUIRED when the credential_identifier was not returned from the Token Response. It MUST NOT be used otherwise. String that determines the format of the Credential to be issued. Credential Format Profiles consist of the Credential format specific parameters.
proof	object	OPTIONAL. Object containing the proof of possession of the cryptographic key material the issued Credential would be bound to.
- proof_type	string	REQUIRED. String denoting the key proof type. Determines other parameters in the key proof object and its respective processing rules. Key proof types defined in this specification can be found in Section 7.2.1.
credential_identifier	string	REQUIRED when credential_identifier was returned from the Token Response. It MUST NOT be used otherwise. Identifies a Credential that is being requested to be issued.
credential_response_encryption	object	OPTIONAL. Object containing information for encrypting the Credential Response. If this request element is not present, the corresponding credential response returned is not encrypted.
- jwk	object	REQUIRED. Object containing a single public key as a JWK used for encrypting the Credential Response.
-- alg	string	REQUIRED. JWE [RFC7516] alg algorithm [RFC7518] for encrypting Credential Responses.
-- enc	string	REQUIRED. JWE [RFC7516] enc algorithm [RFC7518] for encrypting Credential Responses.

The proof_type parameter is an extension point that enables the use of different types of proofs for different cryptographic schemes.

The proof element MUST incorporate the Credential Issuer Identifier (audience), and a c_nonce value generated by the Authorization Server or the Credential Issuer to allow the Credential Issuer to detect replay. The way that data is incorporated depends on the key proof type.

The initial c_nonce value can be returned in a successful Token Response, in a Credential Error Response or in a Batch Credential Error Response.

The Credential Issuer indicates support for encrypted responses by including the credential_response_encryption parameter in the Credential Issuer Metadata.

/credential_offer

Description: Provides information about an offer for a verifiable credential or transaction ID, including terms and associated details.
Endpoint: /credential_offer
HTTP Method: GET
Parameters:

Parameter	Type	Description
credential_issuer	string	REQUIRED. The URL of the Credential Issuer, as defined in Section 11.2.1, from which the Wallet is requested to obtain one or more Credentials. The Wallet uses it to obtain the Credential Issuer's Metadata.
credential_configuration_ids	array	REQUIRED. Array of unique strings that each identify one of the keys in the name/value pairs stored in the credential_configurations_supported Credential Issuer metadata. The Wallet uses these string values to obtain information about the Credential being offered.
grants	object	OPTIONAL. Object indicating to the Wallet the Grant Types the Credential Issuer's Authorization Server is prepared to process for this Credential Offer.
- authorization_code	object	Grant Type authorization_code. OPTIONAL. Object representing parameters for the Authorization Code grant type.
-- issuer_state	string	OPTIONAL. String value created by the Credential Issuer and opaque to the Wallet. Used to bind the subsequent Authorization Request with the Credential Issuer.
-- authorization_server	string	OPTIONAL. String that the Wallet can use to identify the Authorization Server when authorization_servers parameter in the Credential Issuer metadata has multiple entries.

Response Format:
- JSON with information about the Credential Offer. The Wallet does not create a response; UX control stays with the Wallet after completion of the process.

Sending Credential Offer by Value:

GET /credential_offer?credential_offer=%7B%22credential_issuer%22:%22https://credential-issuer.example.com%22,%22credential_configuration_ids%22:%5B%22UniversityDegreeCredential%22,%22org.iso.18013.5.1.mDL%22%5D,%22grants%22:%7B%22urn:ietf:params:oauth:grant-type:pre-authorized_code%22:%7B%22pre-authorized_code%22:%22oaKazRN8I0IbtZ0C7JuMn5%22,%22tx_code%22:%7B%22input_mode%22:%22numeric%22,%22length%22:4,%22description%22:%22Please%20provide%20the%20one-time%20code%20that%20was%20sent%20via%20e-mail%22,%22interval%22:5%7D%7D%7D%7D%7D

Sending Credential Offer by Reference:

GET /credential_offer_uri=https%3A%2F%2Fserver%2Eexample%2Ecom%2Fcredential-offer.json HTTP/1.1
Host: server.example.com

Credential Offer Response Example:

{
    "credential_issuer": "https://credential-issuer.example.com",
    "credential_configuration_ids": ["UniversityDegreeCredential"],
    "grants": {
        "authorization_code": {
            "issuer_state": "eyJhbGciOiJSU0Et...FYUaBy"
        }
    }
}

Credential Offer Object Example:

{
   "credential_issuer": "https://credential-issuer.example.com",
   "credential_configuration_ids": [
      "UniversityDegreeCredential",
      "org.iso.18013.5.1.mDL"
   ],
   "grants": {
      "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
         "pre-authorized_code": "oaKazRN8I0IbtZ0C7JuMn5",
         "tx_code": {
            "length": 4,
            "input_mode": "numeric",
            "description": "Please provide the one-time code that was sent via e-mail"
         }
      }
   }
}

/authorize

Description: Initiates the authorization process for obtaining a verifiable credential.
Endpoint: /authorize
HTTP Method: GET
Parameters:

Parameter	Description	Example
`response_type`	REQUIRED. Specifies the desired response type. Should be set to `code`.	`code`
`client_id`	REQUIRED. The client identifier.	`s6BhdRkqt3`
`code_challenge`	REQUIRED. Code challenge generated by the client for PKCE [RFC7636].	`E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM`
`code_challenge_method`	REQUIRED. Method used for code challenge. Should be set to `S256` for PKCE.	`S256`
`authorization_details`	OPTIONAL. Authorization details for specifying the Credential to be obtained. It is an array of objects, e.g., `[{"type": "openid_credential", "credential_configuration_id": "UniversityDegreeCredential"}]`.	See example in the documentation for line breaks.
`scope`	OPTIONAL. Requested scope for Credential issuance using OAuth 2.0 scope parameter.	`UniversityDegreeCredential`
`resource`	OPTIONAL. Value is the Credential Issuer's identifier for differentiating Credential Issuers when authorization_servers parameter is present in Credential Issuer metadata.	`https://credential-issuer.example.com`
`redirect_uri`	REQUIRED. The redirection URI to which the response will be sent.	`https%3A%2F%2Fclient.example.org%2Fcb`
`wallet_issuer`	OPTIONAL. Wallet's identifier. RECOMMENDED in Dynamic Credential Requests.	`wallet-issuer-id`
`user_hint`	OPTIONAL. Opaque End-User hint for optimizing the End-User's experience. RECOMMENDED in Dynamic Credential Requests.	`user-hint`
`issuer_state`	OPTIONAL. Identifies a certain processing context at the Credential Issuer. Typically passed in a Credential Offer from the Issuer.	`issuer-state-value`

/batch_credential

Description: Issues multiple verifiable credentials or transaction IDs in a batch, preparing the corresponding credential responses.
Endpoint: /batch_credential
HTTP Method: POST
Parameters:

Parameter	Description
`credential_requests`	REQUIRED. Array containing Credential Request objects, as defined in Section 7.2.

Batch Credential Request Example

POST /batch_credential HTTP/1.1
Host: server.example.com
Content-Type: application/json
Authorization: BEARER czZCaGRSa3F0MzpnWDFmQmF0M2JW

{
   "credential_requests":[
      {
         "format":"jwt_vc_json",
         "credential_definition": {
           "type":[
             "VerifiableCredential",
             "UniversityDegreeCredential"
           ]
         },
         "proof":{
            "proof_type":"jwt",
            "jwt":"eyJ0eXAiOiJvcGVuaWQ0dmNpL...Lb9zioZoipdP-jvh1WlA"
         }
      },
      {
         "format":"mso_mdoc",
         "doctype":"org.iso.18013.5.1.mDL",
         "proof":{
            "proof_type":"jwt",
            "jwt":"eyJraWQiOiJkaWQ6ZXhhbXBsZ...KPxgihac0aW9EkL1nOzM"
         }
      }
   ]
}

👮 Authorization server

The Authorization server is an OAuth 2.0 Server component facilitates the issuance of access tokens and validation of provided access tokens according to the OAuth 2.0 protocol the grant type should be of the type of Authorization Code flow and support PKCE. Below are the details:

/authz_server/token

Description: Allows clients to obtain an access token using the Authorization Code grant type with Proof Key for Code Exchange (PKCE) for enhanced security.
Endpoint: /authz_server/token
HTTP Method: POST
Parameters:

Parameter	Type	Description
grant_type	string	Authorization Code (required for this grant type)
client_id	string	The client identifier (Required)
code	string	The authorization code received from the authorization server (Required)
redirect_uri	string	The redirect URI used in the initial authorization request (Required)
code_verifier	string	The PKCE code verifier used to generate the initial code challenge (Required)

Response Format:
- JSON with an access token and additional details.

/authz_server/check_token

Description: Validates the provided access token and retrieves details associated with the access token.
Endpoint: /authz_server/check_token
HTTP Method: POST
Parameters:

Parameter	Type	Description
token	string	The access token to be validated (Required)

Response Format:
- JSON with token details and additional information.

🥌 DIDroom Backend

Ask to join an organization

Endpoint: POST /api/collections/orgAuthorizations/records
Functionality:
- Allows a user to request to join an organization.
Parameters:

Parameter	Type	Description
organization	string	Organization ID (Required)
user	string	User ID (Required)
status	string	'pending' (Required)

List of the organizations I'm part of

Endpoint: GET /api/collections/orgAuthorizations/records?filter=(user='{userId}')&&expand=organization&&fields=expand.organization.name
Functionality:
- Lists the organizations a user is part of.
Parameters:

Parameter	Type	Description
userId	string	User ID (Required)

List of services of my organization

Endpoint: GET /api/collections/services/records?filters=(organization='{orgId}')
Functionality:
- Lists services of a specified organization.
Parameters:

Parameter	Type	Description
orgId	string	Organization ID (Required)

List of WebAuthn sessions/devices

Endpoints:
- GET /api/collections/webauthnCredentials/records?filter=(user='{userId}')
- POST /api/collections/sessionDataWebauthn/records?filter=(user='{userId}')
Functionality:
- Lists WebAuthn sessions/devices for a user.
- Initiates a new WebAuthn device registration.
Parameters:

Parameter	Type	Description
userId	string	User ID (Required)

My profile info

Endpoint: GET /api/collections/users/records/:{userId}
Functionality:
- Retrieves the profile information of a user.
Parameters:

Parameter	Type	Description
userId	string	User ID (Required)

Register WebAuthn a new method (device) init

Endpoint: GET /api/webauthn/register/begin/{username}
Functionality:
- Initiates the registration of a new WebAuthn method (device).
Parameters:

Parameter	Type	Description
username	string	User's username (Required)

Register WebAuthn a new method (device) finish

Endpoint: GET /api/webauthn/register/finish/{username}
Functionality:
- Completes the registration of a new WebAuthn method (device).
Parameters:

Parameter	Type	Description
username	string	User's username (Required)

Update profile

Endpoint: POST /api/collections/users/records/:{userId}
Functionality:
- Updates the profile information of a user.
Parameters:

Parameter	Type	Description
userId	string	User ID (Required)

💫 W3C-DID Federated Service

The W3C-DID Federated Services exposes RESTful APIs documented in detail with openAPI standards available on https://did.dyne.org/docs/. Below are the useful calls used in the Didroom components and architecture.

Create DID

HTTP Method: POST
API Endpoint: /api/v1/{domain}/pubkeys-accept.chain
Request Parameters:

Parameter	Type	Description
did_document	JSON	The new DID document in JSON format.
ecdh_signature	string	ECDH signature of the DID document.
timestamp	string	Timestamp to prevent replay attacks.
eddsa_signature	string	EdDSA signature of the DID document.
id	string	DID of the signer.

Response Format:
- JSON with success/failure status and additional details.

Read DID

HTTP Method: GET
API Endpoint: /dids/{DID}
Request Parameters:

Parameter	Type	Description
DID	string	The Decentralized Identifier to be resolved

.|

Response Format:
- JSON containing the resolved DID document or an error.

Update DID

HTTP Method: POST
API Endpoint: /api/v1/{domain}/pubkeys-update.chain
Request Parameters:

Parameter	Type	Description
did_document	JSON	The updated DID document in JSON format.
ecdh_signature	string	ECDH signature of the updated DID document.
timestamp	string	Timestamp to prevent replay attacks.
eddsa_signature	string	EdDSA signature of the updated DID document.
id	string	DID of the signer.

Response Format:
- JSON with success/failure status and additional details.

Deactivate DID

HTTP Method: POST
API Endpoint: /api/v1/{domain}/pubkeys-deactivate.chain
Request Parameters:

Parameter	Type	Description
deactivate_id	string	The DID to be deactivated.
ecdh_signature	string	ECDH signature using admin ECDH key.
id	string	DID of the signer.

Response Format:
- JSON with success/failure status and additional details.

Broadcast to Ganache Blockchain

HTTP Method: POST
API Endpoint: /api/v1/{domain}/pubkeys-broadcast-ganache.chain
Request Parameters:

Parameter	Type	Description
broadcast_id	string	The ID corresponding to the DID document.
timestamp	string	Unix timestamp in milliseconds.
eddsa_signature	string	EdDSA signature of the broadcast data.
id	string	DID of the signer.

Response Format:
- JSON with success/failure status and additional details.

Broadcast to Polygon Blockchain

HTTP Method: POST
API Endpoint: /api/v1/{domain}/pubkeys-broadcast-polygon.chain
Request Parameters:

Parameter	Type	Description
broadcast_id	string	The ID corresponding to the DID document.
timestamp	string	Unix timestamp in milliseconds.
eddsa_signature	string	EdDSA signature of the broadcast data.
id	string	DID of the signer.

Response Format:
- JSON with success/failure status and additional details.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API.md

API.md

API Specs for DIDroom Solution Components

Introduction

🪪 Credential Issuer

/credential

/credential_offer

Sending Credential Offer by Value:

Sending Credential Offer by Reference:

Credential Offer Response Example:

Credential Offer Object Example:

/authorize

/batch_credential

Batch Credential Request Example

👮 Authorization server

/authz_server/token

/authz_server/check_token

🥌 DIDroom Backend

Ask to join an organization

List of the organizations I'm part of

List of services of my organization

List of WebAuthn sessions/devices

My profile info

Register WebAuthn a new method (device) init

Register WebAuthn a new method (device) finish

Update profile

💫 W3C-DID Federated Service

Create DID

Read DID

Update DID

Deactivate DID

Broadcast to Ganache Blockchain

Broadcast to Polygon Blockchain

Files

API.md

Latest commit

History

API.md

File metadata and controls

API Specs for DIDroom Solution Components

Introduction

🪪 Credential Issuer

/credential

/credential_offer

Sending Credential Offer by Value:

Sending Credential Offer by Reference:

Credential Offer Response Example:

Credential Offer Object Example:

/authorize

/batch_credential

Batch Credential Request Example

👮 Authorization server

/authz_server/token

/authz_server/check_token

🥌 DIDroom Backend

Ask to join an organization

List of the organizations I'm part of

List of services of my organization

List of WebAuthn sessions/devices

My profile info

Register WebAuthn a new method (device) init

Register WebAuthn a new method (device) finish

Update profile

💫 W3C-DID Federated Service

Create DID

Read DID

Update DID

Deactivate DID

Broadcast to Ganache Blockchain

Broadcast to Polygon Blockchain