# Dentity API Services
## Introduction
Dentity provides API services for enterprise users to perform functions on the Dentity platform, including verifying age and identity, creating Dentity cloud wallets, and issuing and verifying credentials. To get started, users must have a Dentity enterprise account. Once created, you will get access to the API keys necessary to perform the functions in this documentation. Please visit to create an account or email for assistance.
## Want to jump right in?
Feeling like an eager beaver? Jump in to the quick start docs and get making your first API request:
{% content-ref url="/pages/rnT8SCx80vr60uFq2uNl" %}
[Reference](/reference/verify-age-and-identity)
{% endcontent-ref %}
Or we offer an Open-Source library that leverages our partnership with the Ethereum Name Service to access our verified Proof of Personhood and Socials
{% embed url="" %}
# Verify Age and Identity
To get started, users must have a Dentity enterprise account. Once created, you will get access to the API keys necessary to perform the functions in this documentation. Please visit to create an account or email for assistance.
{% hint style="info" %}
If you haven't already, please create an enterprise account on Dentity.
{% endhint %}
{% content-ref url="/pages/clMQAx3EOdmy3xABJQDg" %}
[Client Documentation](/reference/verify-age-and-identity/client-documentation)
{% endcontent-ref %}
{% content-ref url="/pages/Kx3dZCq3h7b20IFSMQiF" %}
[Server Documentation](/reference/verify-age-and-identity/server-documentation)
{% endcontent-ref %}
# Client Documentation
**Dentity** verification popup is provided by a single Javascript file. It will add a popup to the DOM. There are some special configurations provided and some functions are used to listen for events that occur during the popup’s lifecycle.
### **Step 1: Add verify button**
Add a button tag or any other tag used to catch the event that calls the popup verification.
```html
```
### **Step 2: Add Dentity script**
Add a script below to load a single Javascript file. Which is provided to add popups to the DOM. The script should be added at the end of the body tag and the bottom of the selector tag declared at **Step 1.**
```html
```
### **Step 3: Configuration Dentity Popup**
Configure **Dentity pop-up** and handle methods provided by **Dentity**.
```html
```
This script needs to be added below the script added in **Step 2**.
Here are two additional mandatory settings:
Option Name
Description
element
(required)
A DOMString containing one or more selectors to match. This string must be a valid CSS selector string; if it isn’t, a SyntaxError exception is thrown. See Locating DOM elements using selectors for more about selectors and how to manage them.
Example: #button-selector
key
(required)
The API key for your domain. You can add a domain on the Dentity business site and get this key. Example: d04c36169f39412696fbf020d793299f1641790047672
**Dentity** also provides some functions to listen for events during the pop-up’s lifecycle:
Function name
Description
onReady
A function that is called when the script has been initialized and is ready to be used. You can use it to check if the Dentity popup is ready before allowing the user to display it.
onShow
A function called when the verification popup is displayed.
onHide
A function called when the verification popup is closed.
onChangeStatus
A function called when verification changes status. There are 3 statuses that can be returned: pending, verified, and failed.
onSubmit
A function that is called before sending the data will generate the verification. It will return the data that will be sent.
onSubmited
A function that is called after creating a successful verification. You can call the onChangeStatus function to be able to get the status of that verification after creating it.
\
# Server Documentation
## Credentials
Find your account's **secret key** and **API keys** in your [website manager](https://business.dentity.com/website-setting).
## API Endpoints
{% hint style="info" %}
**Note:**
* When you send a request, your phone will get an SMS to start the next process.
* If your account is not verified, you have to start the process to verify your account information by **Dentity**’s system first.
{% endhint %}
## Create a new verification
`POST` `https://api.dentity.com/core/api/v1/verification`
This creates a new verification request from a customer’s information.
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ---------------- |
| x-api-key\* | String | Domain’s API Key |
#### Request Body
| Name | Type | Description |
| --------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key\* | String | Your domain’s API Key. |
| metadata | Object |
Custom variable Id or other information { "id":"sample\_15fa31da59f69041641984405622"
}
|
| callbackUrl | String | Partner will get verification status when user start process to verify |
| phoneNumber\* | Object |
Holder phone number. Object includes dialCode and phone
Custom SMS content. The link is required. E.g: {{siteName}} has requested that you verify your information: {{link}}
|
{% tabs %}
{% tab title="200: OK Creating verification successfully" %}
```javascript
{
"data": {
"_id": "6333e7c08372cd0011d974aa", //Unique verification id
"status": "pending" // pending, verified, failed
"metadata": {
"id": "15fa31da59f69041641984405622" // Custom variable Id
}
}
}
```
{% endtab %}
{% tab title="400: Bad Request Phone number and email already exist in 2 different accounts." %}
```javascript
{
message: "The phone or email you entered does not match your account"
}
```
{% endtab %}
{% endtabs %}
{% hint style="success" %}
**metadata:** We recommend passing in the metadata (*userId,email,trackId..*.) as a good way for you to compare the data received correctly with the data on your end.
{% endhint %}
## Get status of a verification request
`GET` `https://api.dentity.com/core/api/v1/verification/:verificationId/status`
This returns the status of a verification request.
#### Path Parameters
| Name | Type | Description |
| ------------------------------------------------ | ------ | ---------------------- |
| verificationId\* | String | Unique verification id |
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ---------------- |
| x-api-key\* | String | Domain’s API Key |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"data": {
"_id": "6333e7c08372cd0011d974aa", //Unique verification id
"status": "verified" //Verification status (pending, verified, failed)
"user": {
"firstName": "Jamie",
"lastName": "Johnston",
"email": "example@dentity.com"
},
"user": {
"firstName": "Jamie",
"lastName": "Johnston",
"fullName": "Jamie Johnston",
"email": "example@dentity.com",
"phoneNumber": "0987654321",
"dateOfBirth": "string",
"addressDetail": {
"street": "string",
"country": "string",
"city": "string",
"state": "string",
"zip": "string"
}
},
"metadata": {
"id": "15fa31da59f69041641984405622" //Custom variable Id
}
}
}
```
{% endtab %}
{% tab title="400: Bad Request Verification not found" %}
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
**PDF file endpoint:** Get verification PDF file is not supported for all IDV provider. Please contact us before you start to use it.
{% endhint %}
## Get verification PDF file
`GET` `https://api.dentity.com/core/api/v1/verification/:verificationId/pdf`
This returns the PDF file of a verification. The PDF file can only be obtained within 24 hours from the time of completing the IDV.
Depending on which Verification Agent you are using, there are two options for retrieving images and files from Dentity. Please ask Dentity support which method is applicable for your account before integrating this API.
#### Path Parameters
| Name | Type | Description |
| ------------------------------------------------ | ------ | ---------------------- |
| verificationId\* | String | Unique verification id |
#### Query Parameters
| Name | Type | Description |
| ----------- | ------- | --------------------------------------------------------------- |
| confidences | Boolean | Include Confidence Scores in the PDF. It's **false** by default |
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ---------------- |
| x-api-key\* | String | Domain’s API Key |
{% tabs %}
{% tab title="200: OK Get PDF of the verification successfully" %}
```json
{
"data":{
"pdf":"KQovQ3JlYXRvciAo/v8AdwBrAGg..." //PDF of the verification in base64
}
}
```
{% endtab %}
{% tab title="400: Bad Request Verification not found" %}
{% endtab %}
{% tab title="400: Bad Request Out of time to get the pdf file" %}
{% endtab %}
{% endtabs %}
## Get bulk verifications
`POST` `https://api.dentity.com/core/api/v1/programmatic/credential/bulk`
Limit of 50 records in a request.
#### Request Body
| Name | Type | Description |
| ------------------------------------------------- | ----- | ------------------------------------------------------------------------ |
| verificationIds\* | Array |
|
{% tabs %}
{% tab title="200: OK Get verifications successfully " %}
```json
{
"data": {
"totalItem": 2,
"data": [
{
"status": "verified",
"_id": "62cd36133fa924001195d809",
"user": {
"firstName": "Lisa",
"lastName": "Lowse"
},
"metadata": {
"_id": "62cff0776fc2c200114773fe"
}
},
{
"status": "verified",
"_id": "62ce91cd291e000011bc2adf",
"user": {
"firstName": "Antoni",
"lastName": "Young"
},
"metadata": {
"_id": "62cff0776fc2c200114773ff"
}
}
],
"page": 1,
"pageSize": 2,
"totalPage": 1
}
}
```
{% endtab %}
{% endtabs %}
## Verification Webhook
In this case you will likely need to know when the customer is verified so that you can approve their order. This can be done using the **callbackUrl** option, which will make a request from our system to yours when the verification status is updated, such as when the verification is verified or failed.
We will send a **PUT request** to the **callback URL** with the following data in JSON format.
**Webhook type:**
Type
Description
verification_status
Verification status change
email_delivery_status
Email delivery status change
sms_delivery_status
SMS delivery status change
1. **verification\_status** will be sent when the status of verification changes
{% hint style="info" %}
**idvImages** are not returned for all IDV providers. So contact us before you start using it.
{% endhint %}
```javascript
{
"type": "verification_status",
"_id": "6333e7c08372cd0011d974aa",
"status": "verified",
"user": {
"firstName": "Jamie",
"lastName": "Johnston",
"fullName": "Jamie Johnston",
"email": "example@dentity.com",
"phoneNumber": "0987654321",
"dateOfBirth": "string",
"addressDetail": {
"street": "string",
"country": "string",
"city": "string",
"state": "string",
"zip": "string"
}
},
"metadata": {
"id": "sample_15fa31da59f69041641984405622"
},
// idvImages are not returned for all IDV providers. So contact us before you start using it.
"idvImages": [
{
"category": "drivers_license",
"images": {
"cropped_back": null,
"cropped_front": null,
"face": "https://documentary-assets-production-sandbox-cognito-us-west-2.s3.us-west-2.amazonaws.com/flwses_5YcEVAaJhGHbmP/1/r/rLsqCopvKH675Klm.jpeg?response-content-disposition=attachment%3B%20filename%3Dface.jpeg&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATAVOPDHKTR4VVYBD%2F20230520%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230520T044527Z&X-Amz-Expires=60&X-Amz-SignedHeaders=host&X-Amz-Signature=187a35670d9fe3b7d175a44b41c01a6ff5649f391febc3ae381022e0ec070207",
"original_back": "https://documentary-assets-production-sandbox-cognito-us-west-2.s3.us-west-2.amazonaws.com/flwses_5YcEVAaJhGHbmP/1/back.jpeg?response-content-disposition=attachment%3B%20filename%3Doriginal_back.jpeg&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATAVOPDHKTR4VVYBD%2F20230520%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230520T044527Z&X-Amz-Expires=60&X-Amz-SignedHeaders=host&X-Amz-Signature=206ed0b1c7dbfb436e515a0eba68649c7ceb866ba62bd9757747579dbe240a71",
"original_front": "https://documentary-assets-production-sandbox-cognito-us-west-2.s3.us-west-2.amazonaws.com/flwses_5YcEVAaJhGHbmP/1/front.jpeg?response-content-disposition=attachment%3B%20filename%3Doriginal_front.jpeg&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIATAVOPDHKTR4VVYBD%2F20230520%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230520T044527Z&X-Amz-Expires=60&X-Amz-SignedHeaders=host&X-Amz-Signature=aaf53c1b1694ab2de0474c4ea240f8d53569798a557d9bee4c527a3fba096262"
}
}
]
}
```
2. **email\_delivery\_status** will be sent when the email sending status change
```json
{
"type": "email_delivery_status"
"_id": "64708367f13bbe00118e82a3",
"status": "pending",
"emailDeliveryEvents": [
{
"email": "thangdd@vmodev.com",
"timestamp": 1685095273,
"status": "delivered"
},
{
"email": "thangdd@vmodev.com",
"timestamp": 1685095271,
"status": "processed"
}
]
}
```
Email delivery events include `processed`, `dropped`, `delivered`, `deferred`, and `bounce`.
Status
Description
processed
Message has been received and is ready to be delivered.
dropped
You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if Spam Checker app is enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota
delivered
Message has been successfully delivered to the receiving server.
deferred
Receiving server temporarily rejected the message.
bounce
Receiving server could not or would not accept mail to this recipient permanently. If a recipient has previously unsubscribed from your emails, the message is dropped.
blocked
Receiving server could not or would not accept the message temporarily. If a recipient has previously unsubscribed from your emails, the message is dropped.
3. **sms\_delivery\_status** Dentity will send an update to that URL every time the status changes; Values include `accepted`, `sending`, `sent`, `failed`, and `delivered`.
```json
{
"type": "sms_delivery_status",
"_id": "64708367f13bbe00118e82a3",
"status": "pending",
"smsDeliveryEvents": {
"to": "+16162904619",
"status": "sent"
}
}
```
The request will also have the “**Dentity-Signature**” header which should be used to verify that the request came from us. Below is an example in NodeJS:
{% tabs %}
{% tab title="Javascript" %}
{% code lineNumbers="true" %}
```javascript
const crypto = require('crypto');
function verifySignature(data, headers) {
const key = headers['Dentity-Signature'];
const hash = crypto
.createHmac('sha256', 'SECRET KEY')
.update(JSON.stringify(data))
.digest('base64');
return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(key));
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% hint style="info" %}
**Note:** If you would like to receive a webhook for all requests, contact us to set up an automatic webhook for your account.
{% endhint %}
# Wallets & Credentials
**Dentity** provides APIs for creating applications, in addition to annotations. Programmatic APIs allow applications to dynamically generate options on the fly, and also allow the creation of idiom domain-specific languages for handling command line arguments.
# Prerequisites
{% hint style="info" %}
**API key**: To get an API key, you must have a **Dentity** enterprise account. If you haven't already done so, please create an account on [`this site`](https://business.dentity.com/auth/sign-up/).
{% endhint %}
### **Create a Credential Template in Dentity Enterprise Account**
After an enterprise account has been created, a credential issuer will need to create a valid template before you can get an **API key**.
* On main page, select "**Issue and Verify Credentials"**
* In the top navigation bar, select "**Credentials**"
* Click on "**Create New Credential**"
* Now, the issuer will need to create a credential template. Fill in all required fields and add any custom data fields to your credential. Select “Create Credential” after you’ve finished
### **Get an API key**
After a credential template has been successfully created, click "**Issue Credential**". Click "**Get API Key**" to get your **API key**. You can copy your **API key** using the copy icon.
# API Endpoints
This documentation should be used to create wallets and issue and manage credentials on the **Dentity** platform. To obtain an API key, Dentity enterprise account is required. Easy sign-up is located [here](https://business.dentity.com/auth/sign-up).
# Wallet
User wallet
Each Dentity user will have a corresponding wallet. This wallet will be used to save credentials that are issued by the issuer through Dentity. You can see more about how a credential is added to a wallet [here](/reference/wallets-and-credentials/api-endpoints/credential).
{% hint style="info" %}
A user will be created when you call API to create a wallet successfully. If the user already has a Dentity wallet, the API will return the wallet ID.
{% endhint %}
## Create Wallet
`POST` `https://api.dentity.com/core/api/v1/programmatic/wallet`
This is the first step in the process. A Dentity wallet must be created before any credentials can be issued to the wallet holder.
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key\* | String | API Key |
#### Request Body
| Name | Type | Description |
| --------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| firstName\* | String | First name |
| phoneNumber\* | Object |
Phone number {
"dialCode": "+1",
"phone": "2048089972" }
|
| email\* | String | Email |
| lastName\* | String | Last name |
{% tabs %}
{% tab title="200: OK Create a new wallet successfully. User wallet address will be returned." %}
```javascript
{
walletId: "62ccf87d452c6c3ab43a815e"
}
```
{% endtab %}
{% tab title="400: Bad Request Occurs when a phone number or email already exists in the Dentity system or when the wrong data type is entered." %}
```javascript
{
message: "User email or phone number already exists or wrong data type"
}
```
{% endtab %}
{% tab title="500: Internal Server Error Please contact the Dentity system administrator as soon as possible" %}
```javascript
{
// Response
}
```
{% endtab %}
{% endtabs %}
# Template
Credential Template
Every issued credential will be based on a template as a standard. So the credential template will be used to define the required fields, the corresponding data type, and the issuer ... Later verifiers can be able to rely on it to determine the exact type of credential they want to verify.
{% hint style="info" %}
Each template will belong to a business as a credential issuer
{% endhint %}
## Create Template
`POST` `https://api.dentity.com/core/api/v1/programmatic/credential/template`
Creates a new credential template.
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key\* | String | API Key |
#### Request Body
| Name | Type | Description |
| ------------------------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| logoURL\* | String | Image template |
| credentialIssuer\* | String | Credential issuer name |
| credentialExpiration\* | String | Date and time credential expires |
| descriptions\* | Array | Description for **customFields** |
| customFields\* | Array |
Field when you want to add in attribute field. Ex: \[
Credential expiration. NOTE: It must be greater than the current date and less or equal than template expiration.
|
| credentialTemplateId\* | String | Template ID |
{% tabs %}
{% tab title="200: OK Issue credential successfully" %}
```javascript
{
"data": {
"credentialId": "654cb11409081b002b4f782f",
"templateId": "654856f46e1395002b6d9526"
}
}
```
{% endtab %}
{% tab title="400: Bad Request Occurs when a phone number or email already exists in the Dentity system or when the wrong data type is entered." %}
```javascript
{
"code": "bad_request",
"message": "This credential already exists in wallet",
"errors": {
"message": "This credential already exists in wallet",
"code": "bad_request",
"status": 400
}
}
```
{% endtab %}
{% endtabs %}
## Get Credential Detail
`GET` `https://api.dentity.com/core/api/v1/programmatic/credential/:id`
Fetches credential details
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ------------- |
| id\* | String | Credential ID |
{% tabs %}
{% tab title="200: OK Get credential detail successfully" %}
```json
{
"data": {
"status": "active",
"isSeparated": false,
"_id": "65374cb71530d2002b5e133d",
"detail": {
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://w3id.org/bbs/v1",
{
"@vocab": "https://trinsic.cloud/dentity-dev/"
}
],
"type": [
"VerifiableCredential",
"IssueTemplateOriginator61dbb8930dfa450011f7d9aa1698122828731"
],
"credentialSchema": [
{
"id": "https://schema.trinsic.cloud/dentity-dev/issue-template-originator-61dbb8930dfa450011f7d9aa-1698122828731",
"type": "JsonSchemaValidator2018"
}
],
"credentialSubject": {
"credentialIssuer": "Issue Template Originator",
"credentialType": "Issue Template Originator",
"holderFullName": "Leslie Knope",
"id": "urn:vc:subject:0"
},
"id": "urn:vc",
"issuanceDate": "2023-10-24T04:48:55Z",
"credentialStatus": {
"id": "https://dentity-dev.connect.trinsic.cloud/credential-status/W9U5cYArzKKuFZE6yY7wQH#0",
"type": "RevocationList2020Status",
"revocationListIndex": "0",
"revocationListCredential": "https://dentity-dev.connect.trinsic.cloud/credential-status/W9U5cYArzKKuFZE6yY7wQH"
},
"issuer": "did:web:dentity-dev.connect.trinsic.cloud:z8wCvUe4sM5eTnYYHFaxxjs",
"proof": {
"type": "BbsBlsSignature2020",
"created": "2023-10-24T04:48:55Z",
"proofPurpose": "assertionMethod",
"proofValue": "lIhBZ7yg99DPjYYyp98f1q+YayTt3vrW0VTz3Jmja6n+J5zFBA1SfDo/F5Nl4ffBFyuoonXH+p3MRILXXzMQ/y9q/R5d68jR4r9M753HBuVdhq2pq7r4VJGFMq/NebGEbu1OBrVuVjhtYsxHR2U/5g==",
"verificationMethod": "did:web:dentity-dev.connect.trinsic.cloud:z8wCvUe4sM5eTnYYHFaxxjs#z9KMl1J5wRrDBZ2J4m5P3EUqo4F86pHgCmLeT5Bviqo"
}
},
"templateId": "urn:template:dentity-dev:issue-template-originator-61dbb8930dfa450011f7d9aa-1698122828731",
"templateName": "Issue Template Originator",
"credentialId": "65374cb71530d2002b5e133d",
"template": "65374c4d1530d2002b5e1339",
"partner": "61dbb8930dfa450011f7d9aa",
"credentialSubjectsData": {
"credentialIssuer": "Issue Template Originator",
"credentialType": "Issue Template Originator",
"holderFullName": "Leslie Knope"
},
"offerCredential": "65374cb71530d2002b5e133e",
"dateCreated": "2023-10-24T04:48:55.685Z",
"dateUpdated": "2023-10-24T04:48:55.685Z",
"__v": 0
}
}
```
{% endtab %}
{% endtabs %}
## Delete Credential in Wallet
`DELETE` `https://api.dentity.com/core/api/v1/programmatic/credential/:id`
Deletes a credential by ID.
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ------------- |
| id\* | String | Credential ID |
{% tabs %}
{% tab title="200: OK Delete credential successfully" %}
```json
{
"data": {
"isSuccess": true
}
}
```
{% endtab %}
{% endtabs %}
## Verify Credential Proof
`POST` `https://api.dentity.com/core/api/v1/credential/proofs/verify`
Verify proof that you received when Holder finished [OIDC for Verifiable Presentation](/reference/wallets-and-credentials/openid-for-verifiable-credentials/openid-connect-for-verifiable-presentations).
#### Request Body
| Name | Type | Description |
| ------ | ------------ | ----------- |
| proofs | Array object | |
{% tabs %}
{% tab title="200: OK Verify proof successfully" %}
```json
{
"data": [
{
"isValid": true,
"validationResults": {
"CredentialStatus": {
"isValid": true,
"messages": []
},
"IssuerIsSigner": {
"isValid": true,
"messages": []
},
"SchemaConformance": {
"isValid": true,
"messages": []
},
"SignatureVerification": {
"isValid": true,
"messages": []
},
"TrustRegistryMembership": {
"isValid": true,
"messages": []
}
}
}
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
**Validation results**: The verification process performs a number of validations, each of which may fail independently of the others.
{% endhint %}
For example, a credential may be expired or revoked, but otherwise perfectly valid.\
`validation_results` contains an entry for each of the following verification steps:
| Name | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SignatureVerification` | The cryptographic proof over the entire Verifiable Credential, specifically using BBS+ Proof of Signature |
| `CredentialStatus` | *(if supported by credential)* Checks if credential has been revoked |
| `SchemaConformance` | Ensures credential conforms with its schema. It is possible to issue a credential omitting a required field (as captured in the credential template). If your use case allows this kind of omission, you can ignore this validation entry. |
| `TrustRegistryMembership` | *(if relevant)* Verifies that credential issuer is an authorized member of the credential's governing Trust Registry |
| `IssuerIsSigner` | Document `issuer` is same DID as document signer. *If false, it is not safe to assume that the claimed `issuer` actually issued the credential.* |
# OpenID for Verifiable Credentials
## What is OpenID Connect
> OpenID Connect is an interoperable authentication protocol based on the OAuth 2.0 framework of specifications (IETF RFC 6749 and 6750). It simplifies the way to verify the identity of users based on the authentication performed by an Authorization Server and to obtain user profile information in an interoperable and REST-like manner.
>
> OpenID Connect enables application and website developers to launch sign-in flows and receive verifiable assertions about users across Web-based, mobile, and JavaScript clients. And the specification suite is extensible to support a range of optional features such as encryption of identity data, discovery of OpenID Providers, and session logout. - [openid.net](https://openid.net/developers/how-connect-works/)
## **What is OpenID for Verifiable Credentials**
> The OpenID for Verifiable Credentials work is a product of the OpenID Connect Working Group. The [whitepaper](https://openid.net/wordpress-content/uploads/2022/06/OIDF-Whitepaper_OpenID-for-Verifiable-Credentials-V2_2022-06-23.pdf) OpenID for Verifiable Credentials describes the work and its motivations. - [openid.net](https://openid.net/sg/openid4vc/)
OpenID for Verifiable Credentials consists of three specifications:
* [OpenID for Verifiable Presentations](/reference/wallets-and-credentials/openid-for-verifiable-credentials/openid-connect-for-verifiable-presentations) - ***Dentity** supported*
* OpenID for Verifiable Credential Issuance - *coming soon*
* Self-Issued OpenID Provider v2 - *coming soon*
**Dentity** based on OpenID provides the simplest way to create a closed flow between issuer and holder and verifier. It makes it easy for the issuer to issue credentials to holders. Verifier easily verifies and identifies holder credentials issued by the issuer.
###
# OpenID Connect for Verifiable Presentations
## Overview
**Dentity** provides a way for verifiers to request holders to share their credentials to verify easily and securely using [OpenID Connect](https://openid.net/developers/how-connect-works/) (OIDC). Specifically in this specification we build and follow [OpenID Connect for Verifiable Presentations](https://openid.net/specs/openid-connect-4-verifiable-presentations-1_0-07.html) and [W3C Verifiable Credentials](https://www.w3.org/TR/vc-data-model/#presentations).
## Usage
### Prerequisites
You need some of the following to get started:
* Access to [Denity Business](https://business.dentity.com/) site to create OIDC client. If you didn't, contact us to get support.
* Have a basic understanding of [OpenID Connect](https://openid.net/developers/how-connect-works/) (OIDC) and related concepts.
* Have created OIDC client.
### Configuration
Create OIDC client in [Denity Business](https://business.dentity.com/) site and get the configuration. Configure the OIDC library you use with the parameters below.
Authority URL: `https://oidc.dentity.com/oidc/auth`
Parameter
Description
client_id
A unique string that you receive after creating the client to identify the application
redirect_uri
The URL will be redirected after the user has verified successfully
response_type
code
scope
openidprofile
### Response and vp\_token
After the user successfully verify with their credential you will receive the corresponding sample format below.
{% hint style="info" %}
**vp\_token example**: Notice that the data below has been changed for brevity.
{% endhint %}
```json
{
"access_token": "fkGh6S2437IaX4YfM0Eumv_2QCjbl14Z1MybzUeQf3r",
"expires_in": 86400,
"id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
"scope": "openid profile",
"token_type": "Bearer",
"vp_token": [
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://w3id.org/bbs/v1",
...
],
"id": "urn:vc",
"type": [
"VerifiedPhoneNumber",
"VerifiableCredential"
],
"credentialSchema": {
"id": "...",
"type": "JsonSchemaValidator2018"
},
"credentialStatus": {
"id": "urn:revocation-registry:dentity:KZswpDQWysmHYy...",
"type": "RevocationList2020Status",
"revocationListCredential": "urn:revocation-registry:dentity:KZswpDQWysmHYy...",
"revocationListIndex": "147"
},
"credentialSubject": {
"id": "urn:vc:subject:0",
"credentialIssuer": "...",
"credentialType": "...",
"holderFullName": "...",
"phoneNumber": "..."
},
"issuanceDate": "2023-07-19T03:02:53Z",
"issuer": "did:ion:test:EiAMNztHqMNA3MrKg-...",
"proof": {
"type": "BbsBlsSignatureProof2020",
"created": "2023-07-19T03:02:53Z",
"nonce": "IZU4ZNyOUzfAqpjCvtgZ...",
"proofPurpose": "assertionMethod",
"proofValue": "ABMH//+V8aQn2fUDpr8a3XGIyosNIVh3LaF0lbjsI...",
"verificationMethod": "did:ion:test:EiAMNztHqMNA3MrKg-dDGJ5...#g2-public"
}
}
]
}
```
The response parameter `vp_token` is defined as follows:
* `vp_token`: a parameter that either directly contains a verifiable presentation or a JSON array with multiple verifiable presentations
* A `vp_token` MUST be provided in the same response as the `id_token` of the respective OpenID Connect transaction. Depending on the response/grant type, this can be either the authentication response or the token response.
* The `vp_token` either contains a single verifiable presentation or an array of verifiable presentations.
### Verify the proof
When the user verifies successfully. You will get vp\_token. Before you start using that data, we recommend you verify it first.
The proof can be verified with:
* Libraries that support VC verifications for [BBS+ signatures](https://identity.foundation/bbs-signature/draft-irtf-cfrg-bbs-signatures.html).
* Call [Dentity's API](/reference/wallets-and-credentials/api-endpoints/credential#verify-credential-proof) to verify the proof
{% hint style="warning" %}
**Verify the proof:** \
Always verify the proof before making use of its data. You can rely on the return value when verifying to use it for your purposes.
Without verification, the received proof is of no more value than an unsubstantiated claim made by your user.
{% endhint %}
## OIDC client libraries
Currently, there are many libraries/packages that support OIDC client integration for most languages. You can view some of the certified packages from [OpenID Connect](https://openid.net/certified-open-id-developer-tools/):
* `Typescript/Javascript` [oidc-client](https://www.npmjs.com/package/openid-client)
* `C#` [IdentityModel.OidcClient](https://github.com/IdentityModel/IdentityModel.OidcClient2)
* `Golang` [OIDC v0.15.7](https://github.com/zitadel/oidc)
* `Java` [GKIDP Broker 1.0.0](https://www.kinto-technologies.com/)
* `Python` [pyoidc](https://github.com/CZ-NIC/pyoidc)
* `Ruby` [openid\_connect](https://github.com/nov/openid_connect)