# UAE PASS

**UAE PASS** is a foundational platform to accelerate the transformation towards a digital based economy and digital society. This platform enables UAE PASS users to register and authenticate themselves in a system integrated with **SP**s (**S**ervice **P**roviders) across UAE. 

UAE PASS Mobile App is a digital idSP for secure online identification. It is an easy and safe service that gives the user access to various authentication and signature services within the UAE. UAE PASS is part of the Smart Government National Plan initiative managed by Digital Dubai (DDA), Telecommunications and Digital Government Regulatory Authority (TDRA), & Abu Dhabi Digital Authority (ADDA) to provide users with a single profile to access all services across UAE SPs. 

**There are 3 main capabilities offered by UAE PASS:** 

1\. Authentication (Available for Government Entities and Private Organizations) 

2\. Digital Signature & eSeal (Available for Government Entities and Private Organizations) 

3\. Data & Document Sharing (Available for Private Organizations Only) 

{% hint style="info" %}
Note: Document Sharing for Government Entities can be integrated through GSB.
{% endhint %}


# Overview

**UAE PASS Digital ID Authentication** 

This document describes the service provider integration guide with “UAE PASS” a Nationwide Digital Identity and Digital Signature platform using the OAuth 2.0 framework.

The Audience of this guide is those who want to integrate with this API using REST standards. This document describes the operations available and the corresponding input and output parameters when invoking these operations.

## UAEPASS Account Levels

**SOP 1:** Mobile and Email are verified. Emirates ID not verified. \
**SOP 2:** Mobile, Email, and Emirates ID are verified. \
**SOP 3:** Mobile, Email, and Emirates ID are verified. 

![Figure 1: Account Levels](/files/-MkeqQJRYRyyTOqT2-RM)


# Getting Onboarded with UAE PASS

**Are you a service provider looking to integrate UAEPASS features with your web/mobile application?** 

**Let us walk you below through the onboarding process we follow.**


# Onboarding Process for UAE PASS Service Providers

<figure><img src="/files/R27qh5ccC7laT5Skydvp" alt=""><figcaption></figcaption></figure>

#### Following are the main phases of SP onboarding process of UAE PASS.

{% content-ref url="/pages/cBGjKxR3WFWgK6mlFcdj" %}
[Initiation Phase](/getting-onboarded-with-uae-pass/onboarding-process-for-uae-pass-service-providers/initiation-phase)
{% endcontent-ref %}

{% content-ref url="/pages/S6APjOiboT6IHaFACH7q" %}
[Development Phase](/getting-onboarded-with-uae-pass/onboarding-process-for-uae-pass-service-providers/development-phase)
{% endcontent-ref %}

{% content-ref url="/pages/rEVmqn8TqIUKM4VQUjoe" %}
[Assessment Phase](/getting-onboarded-with-uae-pass/onboarding-process-for-uae-pass-service-providers/assessment-phase)
{% endcontent-ref %}

{% content-ref url="/pages/A07G66h7SwczzAtCU7aR" %}
[Go live Phase](/getting-onboarded-with-uae-pass/onboarding-process-for-uae-pass-service-providers/go-live-phase)
{% endcontent-ref %}

***


# Initiation Phase

<table><thead><tr><th width="91" data-type="number">Step</th><th>Activities</th><th>Responsibility</th></tr></thead><tbody><tr><td>1</td><td>Service provider to initiate the request for integration with UAEPASS through the Developer Portal (<a href="https://uaepass.ae/developers"><mark style="color:green;">UAE PASS | Developers</mark></a>). (Please make sure to mention the entity type as Government or Private.)</td><td>Service Provider</td></tr><tr><td>2</td><td>Acknowledge and request for valid UAE Trade license for private entities. The respective onboarding team will guide you through the integration process based on the emirate you are registered.</td><td>Onboarding Team</td></tr><tr><td>3</td><td>Share the welcome email including UAEPASS reference documentation/videos and required information to start the onboarding process.</td><td>Onboarding Team</td></tr><tr><td>4</td><td><p>Service provider to share the filled questionnaires relevant to UAEPASS features going to be integrated.</p><p></p><p> <mark style="color:green;">1</mark>. <a href="#authentication-questionnaire"><mark style="color:green;">Authentication Questionnaire</mark></a></p><p></p><p> <mark style="color:green;">2</mark>. <a href="#digital-signature-questionnaire"><mark style="color:green;">Digital Signature Questionnaire</mark></a></p><p></p><p><mark style="color:green;">3.</mark><a href="#e-seal-questionnaire"><mark style="color:green;">e-Seal Questionnaire</mark></a><a href="#e-seal-certificate-request-form"> </a></p><p><mark style="color:green;">3.1.</mark><a href="#e-seal-certificate-request-form"><mark style="color:green;">e-Seal Certificate request form</mark></a> <strong>(Applicable if you are integrating e-Seal feature)</strong></p><p></p><ol start="5"><li><a href="#hash-signing-questionnaire"><mark style="color:green;">Hash Signing Questionnaire</mark></a></li><li><a href="#data-sharing-authorization-questionnaire"><mark style="color:green;">Data sharing Authorization Questionnaire.</mark></a></li></ol><p></p></td><td>Service Provider</td></tr><tr><td>5</td><td>Service provider to share workflow diagram for the UAEPASS user journey. (Please refer <a href="/pages/Xvzn1axln52KiJBEO23W"><mark style="color:green;">Use case Guidelines Section</mark> </a>to select the suitable workflow diagram.)</td><td>Service Provider</td></tr><tr><td>6</td><td>Service provider to share UI mockups (Wire frames) for the UAE PASS User Journeys.</td><td>Service Provider</td></tr><tr><td>7</td><td>UAEPASS Onboarding team to evaluate and approve the use case (<strong>Any use cases that deviate from the standard guidelines, i.e., those not following the prescribed Use Case Guidelines, will necessitate approval from management. Please be aware that obtaining this approval may extend the overall processing</strong> <strong>time</strong>.)</td><td>Onboarding Team</td></tr></tbody></table>

### <mark style="color:green;">**Authentication Questionnaire**</mark>

&#x20;<mark style="color:green;">**(Refer**</mark> [<mark style="color:green;">**Authentication Feature**</mark>](/feature-guides/authentication) <mark style="color:green;">**for more information on this feature)**</mark>

{% file src="/files/mHMZ2iWR6ArZWRTCBgLf" %}

### <mark style="color:green;">**Digital Signature Questionnaire**</mark>&#x20;

<mark style="color:green;">**(Refer**</mark> [<mark style="color:green;">**Digital Signature**</mark>](/feature-guides/signature-integration-guide) <mark style="color:green;">**Feature for more information on this feature)**</mark>

{% file src="/files/1ZSJ1NneoQ5KI5RJNFc1" %}

### <mark style="color:green;">**e-Seal Questionnaire**</mark>

&#x20;<mark style="color:green;">**(Refer**</mark> [<mark style="color:green;">**e-Seal Feature**</mark>](/feature-guides/eseal) <mark style="color:green;">**for more information on this feature)**</mark>

{% file src="/files/jaYBF85qIUz4iiHe30gY" %}

### <mark style="color:green;">**e-Seal Certificate Request Form**</mark>

&#x20;<mark style="color:green;">**(Refer**</mark>[ <mark style="color:green;">**e-Seal**</mark>](/feature-guides/eseal) <mark style="color:green;">**Feature for more information on this feature)**</mark>

{% file src="/files/FUwDG5yWFSy4JO4z1gQP" %}

### <mark style="color:green;">**Hash Signing Questionnaire**</mark>

&#x20;<mark style="color:green;">**(Refer**</mark> [<mark style="color:green;">**Hash Signing**</mark>](/feature-guides/signature-integration-guide/hash-signing) <mark style="color:green;">**Feature for more information on this feature)**</mark>

{% file src="/files/tc5rwa1176Hsk6DGWKl6" %}

### <mark style="color:green;">**Data Sharing Authorization Questionnaire**</mark>

&#x20;<mark style="color:green;">**(Refer**</mark> [<mark style="color:green;">**Data Sharing Authorization feature**</mark> ](/feature-guides/data-sharing-authorization)<mark style="color:green;">**for more information on this feature)**</mark>

{% file src="/files/hG81WdrfWZWoXXhGpxTU" %}


# Development Phase

| Step | Activities                                                                                                                                                                                                                                                                             | Responsibility   |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| 1    | Share staging credentials with service provider.                                                                                                                                                                                                                                       | Onboarding Team  |
| 2    | Initiate the SPA/MOU signing process (For private entities-Service Provider Agreement, MOU for Government entities).                                                                                                                                                                   | Onboarding Team  |
| 3    | Service Provider to start the staging environment integration and inform UAEPASS team once completed to schedule the staging assessment. Refer the [<mark style="color:green;">Assessment checklist</mark>](#assessment-check-list) relevant to your integration for verifying points. | Service Provider |

#### <mark style="color:green;">**Assessment Check List**</mark>

{% file src="/files/ov9wG2ujqe0Z3eVkV7KK" %}


# Assessment Phase

<table><thead><tr><th width="87">Step</th><th>Activities</th><th>Responsibility</th></tr></thead><tbody><tr><td>1</td><td>Arranges for the assessment session with the service provider.</td><td>Onboarding Team</td></tr><tr><td>2</td><td>Any issue found in the use case? If yes rectify the issues observed in the initial assessment and requests for another round of assessment.</td><td>Service Provider</td></tr><tr><td>3</td><td>Arranges for second round of assessment with the service provider if issues found in first assessment.</td><td>Onboarding Team</td></tr><tr><td>4</td><td>Verify that service provider complies by all the scenarios as per the <a href="/pages/S6APjOiboT6IHaFACH7q#assessment-check-list"><mark style="color:green;">assessment checklist</mark> </a>before confirms the go live.</td><td>Onboarding Team</td></tr><tr><td>5</td><td>Share video recordings of all the scenarios tested during assessment with   Onboarding Team.</td><td>Service Provider</td></tr><tr><td>6</td><td>Share the video recordings of all the scenarios with the management for approval along with the use case details.</td><td>Onboarding Team</td></tr><tr><td>7</td><td>Review the final use case videos, use case details and approve moving to go live phase.</td><td>Onboarding Team Lead</td></tr><tr><td>8</td><td>SP (PVT only) to complete signing of SPA and share before moving to the Go Live Step.</td><td>Service Provider</td></tr></tbody></table>

{% file src="/files/laXyb4w1bdWSsOiozYHT" %}


# Go live Phase

<table><thead><tr><th width="95">Step</th><th>Activities</th><th>Responsibility</th></tr></thead><tbody><tr><td>1</td><td>Service Provider to share the relevant Go Live form based on the feature integrated.  For Authentication, Digital Signature, Facial bio metrics TC, Web Registration and eSeal features please fill <a href="#go-live-form-for-uae-pass-features-authentication-digital-signature-facial-bio-metric-tc-web-registr"><mark style="color:green;">Go Live form for UAE PASS Features</mark></a> and for Data sharing authorization feature please fill<a href="#go-live-form-data-sharing-authorization"> <mark style="color:green;">Go Live form Data sharing Authorization Feature</mark></a><mark style="color:green;">.</mark></td><td>Service Provider</td></tr><tr><td>2</td><td>Issue Production Credentials.</td><td>Onboarding Team</td></tr><tr><td>3</td><td>Service provider to continue with production environment implementation.</td><td>Service Provider</td></tr><tr><td>4</td><td>Service Provider to inform the Go Live Date</td><td>Service Provider </td></tr><tr><td>5</td><td>Conduct the production assessment.</td><td>Onboarding Team</td></tr><tr><td>6</td><td>Share Service Desk Credentials with Service Provider team to log incidents for post go-live support. </td><td>Onboarding Team</td></tr></tbody></table>

#### <mark style="color:green;">Go‑Live Form for UAE PASS Features (Authentication, Digital Signature, Facial Bio Metric TC, Web Registration & eSeal)</mark>

{% file src="/files/OkaJpAokYNzAlzkLhVJN" %}

{% hint style="warning" %} <mark style="color:$warning;">Note:</mark> <mark style="color:$warning;">Please fill this form if you are integrating with UAE PASS Authentication, Digital Signature, Facial Bio Metric Transaction Confirmation, eSeal or Web Registration features.</mark>
{% endhint %}

#### <mark style="color:green;">Go Live Form for Data Sharing Authorization Feature.</mark>

{% file src="/files/lqjJBFtYfGPzXSczRDcJ" %}

{% hint style="warning" %} <mark style="color:$warning;">Note:</mark> <mark style="color:$warning;">Please fill this form only if you are integrating with UAE PASS  Data Sharing Authorization feature.</mark>
{% endhint %}


# User Account Types

### SOP1: Basic Account

* This account type is unverified.&#x20;
* Email and mobile number are both verified using OTP.&#x20;
* User can create this account without Emirates ID.&#x20;
* User can create this account with Emirates ID, and choose not to continue with verification.&#x20;

#### Benefits:&#x20;

* &#x20;Limited access to services&#x20;
* Verify Document feature is available&#x20;
* No Sign Document feature&#x20;
* No Add Document feature&#x20;

### SOP2: Advanced Account

* This account type is verified.&#x20;
* Email and mobile number are both verified using OTP.&#x20;
* User can create this account with Emirates ID, and choose to continue with verification either by SmartPass or Dubai ID previous accounts OR Emirates ID PIN Registration.

#### Benefits:&#x20;

* Access to all services&#x20;
* Verify Document feature is available&#x20;
* Sign Document feature is available (Signature level is Advanced)&#x20;
* Advanced Signature is the 4 PIN code&#x20;
* No Add Document feature&#x20;

### SOP3: Qualified Account

* This account type is verified.&#x20;
* Email and mobile number are both verified using OTP.&#x20;
* User can create this account with Emirates ID, and choose to continue with verification either by finger biometrics or face biometrics&#x20;

#### Benefits:

* Access to all services&#x20;
* Verify Document feature is available&#x20;
* Sign Document feature is available (Signature level is Qualified)&#x20;
* Advanced Signature is the 6 digit password (Upper, lower case, special character & numbers)
* Add Document feature is available&#x20;

![](/files/ziOTYQ9SePXwvPGq2fxD)


# Create Staging UAE PASS Account

This section describes how you can download and set up the UAE PASS staging application for testing/POC purposes.

## <mark style="color:orange;">Download staging app:</mark>

{% content-ref url="/pages/-Mek\_ukfT0IuZiJ6bZIx" %}
[Staging Apps](/resources/staging-apps)
{% endcontent-ref %}

## <mark style="color:orange;">UAEPASS Basic Account Creation Steps:</mark>

### <mark style="color:blue;">Step 1. Choose</mark> <mark style="color:green;">Create New Account</mark> option to register as new user<mark style="color:purple;">.</mark>

<figure><img src="/files/VaeSfSPaXSY9M74wm4u6" alt="" width="375"><figcaption></figcaption></figure>

<figure><img src="/files/nnxopOqgzfWKKTzgw2qc" alt="" width="375"><figcaption></figcaption></figure>

<figure><img src="/files/5dReTDiHElDtzYCHXn8L" alt="" width="375"><figcaption></figcaption></figure>

### <mark style="color:blue;">Step 2. Accept Terms and Conditions.</mark>&#x20;

<figure><img src="/files/OUvJxWiSkpsiBq4fI0SF" alt="" width="375"><figcaption></figcaption></figure>

<figure><img src="/files/LoN0Cw4xrbbV1LRH96ys" alt="" width="375"><figcaption></figcaption></figure>

### <mark style="color:blue;">Step 3. Choose Proceed as Citizen or Resident Option.</mark>

<figure><img src="/files/xIiRAfVtTtgTE2EX2wZX" alt="" width="375"><figcaption></figcaption></figure>

### <mark style="color:blue;">Step 4.1. If you have Emirates ID Card, choose</mark> <mark style="color:green;">Scan Now</mark> <mark style="color:blue;">option.</mark>&#x20;

#### **4.1.1** Scan the back side of the Emirates ID card (MRZ Code).

<figure><img src="/files/QGW5FNNPcvbTE1DKprvz" alt="" width="375"><figcaption></figcaption></figure>

#### **4.1.2** Confirm the personal details which has been pulled from scanned Emirates ID card.

![](/files/-Ml4FcI01E9pFOPtJzZd)

### <mark style="color:blue;">Step 4.2. If you don't have Emirates ID Card, click on "</mark><mark style="color:green;">I don't have an Emirates ID</mark><mark style="color:blue;">" option and enter details manually.</mark>

<figure><img src="/files/I3fiQFwQCEJjxpUDztvA" alt="" width="375"><figcaption></figcaption></figure>

### <mark style="color:blue;">Step 5. Verify your Mobile Number and Email.</mark>&#x20;

{% hint style="success" %} <mark style="color:green;">**UAE PASS will send OTP to the entered mobile number and email (Kindly make note that this is a Onetime activity only at the time of registration.)**</mark>
{% endhint %}

<figure><img src="/files/1s35weDQqdjdNI4Se5nE" alt="" width="375"><figcaption></figcaption></figure>

#### 5.1 UAE PASS will send OTP to the entered Mobile Number and Email. Provide the OTP number sent to your entered mobile number.&#x20;

<figure><img src="/files/WcOeBJU1w2kaXBJk3G8b" alt="" width="375"><figcaption></figcaption></figure>

#### 5.2 Upon success, you need to follow same steps for Email verification. Provide the OTP sent to your entered email ID.&#x20;

<figure><img src="/files/GgJyMUuOPZITFl92T7It" alt="" width="375"><figcaption></figcaption></figure>

### <mark style="color:blue;">Step 6. Set the PIN number to protect the application after successful verification of mobile number and email address.</mark>&#x20;

<figure><img src="/files/PYOjI162z7yQrzjbUo0B" alt="" width="375"><figcaption></figcaption></figure>

### <mark style="color:blue;">Step 7. All set! Your basic Account is created.</mark>&#x20;

<figure><img src="/files/feJIhD7kWv5EeC7Ci3h5" alt="" width="375"><figcaption></figcaption></figure>

<figure><img src="/files/t6B8rQ21RQRhtY86n28n" alt="" width="375"><figcaption></figcaption></figure>

{% hint style="warning" %}

## <mark style="color:orange;">User will get to upgrade the UAE PASS account from Basic/Unverified to Verified in two ways. But you cannot upgrade your staging UAE PASS account using below two options. Hence click " Later" to proceed.</mark>

{% endhint %}

<figure><img src="/files/5KG8gNsw6RvnT6ZOEZJ9" alt="" width="375"><figcaption></figcaption></figure>

### <mark style="color:red;">Refer below section on how to upgrade to a verified account from basic account.</mark>

{% content-ref url="/pages/4xv2ivyOYMZoCYpYFXHu" %}
[Upgrade Staging UAE PASS Account](/quick-start-guide-uae-pass-staging-environment/upgrade-staging-uae-pass-account)
{% endcontent-ref %}

{% hint style="success" %} <mark style="color:green;">**Accounts can be created in staging from any location as there are no restrictions from UAE PASS end**</mark>
{% endhint %}


# Upgrade Staging UAE PASS Account

Below steps provide you the guide on how to upgrade a basic UAE PASS staging account into a verified account.

{% hint style="danger" %} <mark style="color:orange;">**Kindly note you cannot upgrade the staging UAE PASS account using the Staging UAE PASS App. The FACE ID verification option and Kiosk option will not work in staging UAE PASS app. To upgrade/verify a staging UAE PASS Account you need to use the Staging Self Care Web Portal of UAE PASS.**</mark>
{% endhint %}

## <mark style="color:orange;">**Step 1**</mark>

After completing the steps of creating a basic profile you can now upgrade the staging account and create signing certificates to enable digital signing features and document sharing features of UAE PASS.

#### **Navigate to the selfcare portal**&#x20;

<mark style="color:green;">**<https://stg.uaepass.ae>**</mark>

<figure><img src="/files/8ouKMuLhh6YbgRuomS3M" alt=""><figcaption></figcaption></figure>

## <mark style="color:orange;">Step 2</mark>

**Login to self-care portal using your basic UAE PASS account.**

For this enter the mobile/email/EID used to create the basic staging UAE PASS account.

<figure><img src="/files/7Gx70AMlXdgSNroVNrp1" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/8oWofPRCuXk8WTkjodwk" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/WRLtD9fHTBXNQOWTyJb4" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
Notice the Account type is **Basic** and **Digital Signature is not available**.
{% endhint %}

## <mark style="color:orange;">Step 3</mark>

**Click on Upgrade button on Right top of the page to Upgrade the account.**

<figure><img src="/files/4f9zPoCA1WLazhx8jlb5" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/8ZOqiNdu4rq0YY7yXok5" alt=""><figcaption></figcaption></figure>

## <mark style="color:orange;">Step 4</mark>

**Change the User Type field&#x20;**<mark style="color:green;">**from SOP1 to SOP3**</mark>**.**

<figure><img src="/files/Ut3fTWEwhDfuLT6CKmYB" alt=""><figcaption></figcaption></figure>

## <mark style="color:orange;">Step 5</mark>

**Fill other missing fields and click on Upgrade button. (You can enter a dummy EID value if you do not have an Emirates ID.)**

<figure><img src="/files/psHMJJ3I7yooVBggEQze" alt=""><figcaption></figcaption></figure>

## <mark style="color:orange;">Step 6</mark>

**Logout from the Self-care portal and Login again to reflect the changes.**

<figure><img src="/files/DhsJPs6OwmeKFlLOfv73" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
**Do not downgrade an account from SOP3 to SOP2 or SOP1. The only way to downgrade an account would be through deleting the account from Staging UAE PASS Mobile App and re-creating a basic account again.**
{% endhint %}

## <mark style="color:orange;">Step 7</mark>

**Click on Set Signing credentials button to create signing certificates for the user. This will enable digital signing features and allow you to proceed with document signing using your UAE PASS account.**

<figure><img src="/files/s0fxgzSYM6lmmtSCD2lg" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/IlBzv8jyGZVmhfsHn2mC" alt=""><figcaption></figcaption></figure>

1. <mark style="color:purple;">**Create Qualified Signature Configurations**</mark>

**Click on Create Certificate button under Qualified certificate and create a Signing Password when prompted to create Qualified Signature configurations.**

<figure><img src="/files/9XVbrpiBBa4w6NvGS9c3" alt=""><figcaption></figcaption></figure>

2. <mark style="color:purple;">**Create Advanced Signature Configurations**</mark>

**Click on Create Certificate option under Advanced Certificate to create the Advanced Signature Configurations.**

## <mark style="color:orange;">**All SET!**</mark>

Once created you can see the Signing Credentials are available for the user. Now you can use the Digital Signature feature of UAE PASS using your account.

<figure><img src="/files/EiHi2aEeofwkvSc285Mp" alt=""><figcaption></figcaption></figure>

Notice the account is shown as **verified** and all features are enabled in the staging UAE PASS mobile app.

<figure><img src="/files/8y5AJcYvlaRkwRE0kplG" alt="" width="375"><figcaption></figcaption></figure>

## <mark style="color:orange;">Below is a recording showing the steps we followed above.</mark>

{% file src="/files/lxT3IiGGs5PzANb7pxnK" %}


# Testing Credentials for POC

The below credentials can be used to test **authentication & signing services** offered by UAE Pass on Staging environment.

**Client ID:** sandbox\_stage

**Client Secret:** sandbox\_stage

**Callback URL:** Any preferred URL

{% hint style="danger" %} <mark style="color:green;">The credentials will only work on</mark> <mark style="color:green;"></mark><mark style="color:green;">**staging environment**</mark> <mark style="color:green;"></mark><mark style="color:green;">and should not be used on</mark> <mark style="color:green;"></mark><mark style="color:green;">**production environment.**</mark> <mark style="color:green;"></mark><mark style="color:green;">Kindly use above only for</mark> <mark style="color:green;"></mark><mark style="color:green;">**POC purposes**</mark> <mark style="color:green;"></mark><mark style="color:green;">and separate staging credentials will be issued for the entity during the onboarding process.</mark>
{% endhint %}


# Conduct a POC with UAE PASS Authentication

The following content provides you a step-by-step guide on conducting a simple POC with UAE PASS Authentication Feature using Postman.

## <mark style="color:orange;">Step 1</mark>

#### <mark style="color:blue;">Set up Staging UAE PASS Account</mark>

Before you begin you must set up a UAE PASS staging account following the steps given in <https://docs.uaepass.ae/start-test-environment-implementation/create-uaepass-user><mark style="color:green;">.</mark>

{% hint style="success" %}
**The account can be either basic or verified. UAE PASS Authentication feature will support SOP1, SOP2 and SOP3 user account types.**
{% endhint %}

## <mark style="color:orange;">Step 2</mark> &#x20;

#### <mark style="color:blue;">Invoke the Authorization Request.</mark>

&#x20;You can use following parameter values for POC purpose.

**Authorize Endpoint=** [<mark style="color:green;">https://stg-id.uaepass.ae/idshub/authorize</mark>](https://stg-id.uaepass.ae/idshub/authorize)

**Client\_id**= <mark style="color:green;">sandbox\_stage</mark>

**Scope** =  <mark style="color:green;">urn:uae:digitalid:profile:general</mark>

**Redirect\_uri**= <mark style="color:green;">For this POC we are using <https://localhost:8000>.</mark>

**acr\_values**= <mark style="color:green;">urn:safelayer:tws:policies:authentication:level:low</mark>

#### Sample Request

{% code overflow="wrap" %}

```url
https://stg-id.uaepass.ae/idshub/authorize?response_type=code&client_id=sandbox_stage&scope=urn:uae:digitalid:profile:general&state=HnlHOJTkTb66Y5H&redirect_uri=https://localhost:8000&acr_values=urn:safelayer:tws:policies:authentication:level:low 
```

{% endcode %}

{% hint style="danger" %}
Authorization request should be invoked in browser to obtain user authorization.
{% endhint %}

Once authorization request is invoked user will get the UAE PASS login page to authorize as follows.&#x20;

<figure><img src="/files/UfXAPhzYinOMCC6ukM1y" alt=""><figcaption><p><mark style="color:green;">UAE PASS Login Page</mark></p></figcaption></figure>

## <mark style="color:orange;">Step 3</mark>

#### <mark style="color:blue;">Enter the identifier of UAE PASS staging account (Email or Mobile or EID) and click on Login.</mark>

&#x20;Once you click on Login button you will receive the UAE PASS authentication notification request to the UAE PASS Staging mobile app and a notification request with a specific code in the browser.&#x20;

<figure><img src="/files/CBVuOrjf9YUXJZVl1Mic" alt=""><figcaption><p><mark style="color:green;">Enter Identifier and Click Login</mark></p></figcaption></figure>

<figure><img src="/files/dSwaqxHWHn91xkTXJ9ib" alt=""><figcaption><p><mark style="color:green;">Match the Code with Notification Request in Mobile</mark></p></figcaption></figure>

<figure><img src="/files/fmFhSf0aJVhhGSU4S9eC" alt=""><figcaption><p><mark style="color:green;">Mobile notification Screen</mark></p></figcaption></figure>

## <mark style="color:orange;">Step 4</mark>

#### <mark style="color:blue;">Select the correct code and confirm the notification request.</mark>

<figure><img src="/files/C6zn2V6FzMEvwCWozL22" alt=""><figcaption></figcaption></figure>

## <mark style="color:orange;">Step 5</mark>

#### <mark style="color:blue;">Obtain Authorization Code</mark>

Once the user accepts the notification request, UAE PASS will issue the authorization code in the response header as shown in below example.

#### Sample Response

```
https://localhost:8080/code-bbc69-344553dc-3445fdscc-HnfgmsfsjjH
```

<figure><img src="/files/PHDoSgfxUfhXzLJjVu0N" alt=""><figcaption><p><mark style="color:green;"><strong>Authorization Response</strong></mark></p></figcaption></figure>

## <mark style="color:orange;">Step 6</mark>

#### <mark style="color:blue;">Invoke the Access Token Request to obtain the access token.</mark>&#x20;

You can use following values for the POC.

**Token End point** = [<mark style="color:green;">https://stg-id.uaepass.ae/idshub/token</mark>](https://stg-id.uaepass.ae/idshub/token)

**grant\_type** = <mark style="color:green;">authorization\_code</mark>

**redirect\_uri** = <mark style="color:green;">Redirect URL value used in the authorization request (Step 2).</mark>

**code** = <mark style="color:green;">Authorization code received in authorization response.</mark>

**Authorization Header** = <mark style="color:green;">Base64 encoded (client\_ID : client\_Secret)</mark>

<figure><img src="/files/paWQ8L1CIZ1N0RiM000Y" alt=""><figcaption><p><mark style="color:green;">Token API request Parameters</mark></p></figcaption></figure>

<figure><img src="/files/td6XQicCOZOO5T7RoQaV" alt=""><figcaption><p><mark style="color:green;"><strong>Token API Authorization Header</strong></mark></p></figcaption></figure>

#### Curl Request for Token API

{% code overflow="wrap" %}

```
curl --location --request POST 'https://stg-id.uaepass.ae/idshub/token?grant_type=authorization_code&redirect_uri=https%3A%2F%2Flocalhost%3A8080&code=bbc69c3b-561b-3cc6-a590-16a2bb8448ed' \
--header 'Authorization: Basic c2FuZGJveF9zdGFnZTpzYW5kYm94X3N0YWdl'
```

{% endcode %}

{% hint style="danger" %}
Token request should be a back-channel request and should use postman or as CURL during the POC to invoke the request.&#x20;
{% endhint %}

{% hint style="success" %}
Authorization code is one time usage value and will expire once used to obtain an access token.  Expiry time will be 10 mins.
{% endhint %}

As success response you will receive an access token from UAE PASS as shown in below image.

<figure><img src="/files/SNCmAV4U9VP5TMQuJVfe" alt=""><figcaption><p><mark style="color:green;"><strong>Token API response</strong></mark></p></figcaption></figure>

## <mark style="color:orange;">Step 7</mark>

#### <mark style="color:blue;">Invoke the User Info request to obtain the user details of the authenticated user.</mark>&#x20;

You can use following values for the POC.

**User info Endpoint** = <mark style="color:green;"><https://stg-id.uaepass.ae/idshub/userinfo></mark>

**Bearer Token** = <mark style="color:green;">Access token value received from access token response</mark>.

<figure><img src="/files/IfWrBzbQUVGiFsLtSNgy" alt=""><figcaption><p><mark style="color:green;"><strong>User Info Request</strong></mark></p></figcaption></figure>

#### Curl Request for User Info API

```
curl --location 'https://stg-id.uaepass.ae/idshub/userinfo' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer 221fb1c8-deb7-3fca-b9f6-1d18281f2929'
```

{% hint style="danger" %}
User Info request should be a back-channel request and should use postman or Curl during the POC to invoke the request.&#x20;
{% endhint %}

On success you will receive the user information of the authenticated user from UAE PASS.

<figure><img src="/files/GqNqb9azNz3ZdKgF52xZ" alt=""><figcaption><p><mark style="color:green;"><strong>User Info Response</strong></mark></p></figcaption></figure>

#### <mark style="color:blue;">You can download the postman collection for POC from below attachment.</mark>

{% file src="/files/FYfu6oua8jMuy6NKYwcy" %}


# Authentication

{% content-ref url="/pages/-MekZ9xSbODWJBgyaFmj" %}
[Web Integration](/feature-guides/authentication/web-application)
{% endcontent-ref %}

{% content-ref url="/pages/-Mek\_EDZo3r2QuVwrI08" %}
[Mobile Integration](/feature-guides/authentication/mobile-application)
{% endcontent-ref %}

{% content-ref url="/pages/-MkfhP9YunSwF\_3dUS3l" %}
[Token Validation API](/feature-guides/authentication/token-validation-api)
{% endcontent-ref %}


# Web Integration

### Here are the articles in this Section:

{% content-ref url="/pages/-MekZ9p6eOTVn70icAX9" %}
[Introduction](/feature-guides/authentication/web-application/introduction)
{% endcontent-ref %}

{% content-ref url="/pages/-MekZ9ur4NdJj\_Sl5YRe" %}
[Pre-Requisites](/feature-guides/authentication/web-application/pre-requisites)
{% endcontent-ref %}

{% content-ref url="/pages/-MekZ9gXXJUhqEbofoJG" %}
[Endpoints](/feature-guides/authentication/web-application/endpoints)
{% endcontent-ref %}

{% content-ref url="/pages/-MekZdVuXNkSD7SoQIJs" %}
[1. Authorization Code](/feature-guides/authentication/web-application/1.-obtaining-the-oauth2-access-code)
{% endcontent-ref %}

{% content-ref url="/pages/-MekZ\_djDB775H5QmwNV" %}
[2. Access Token](/feature-guides/authentication/web-application/2.-obtaining-the-access-token)
{% endcontent-ref %}

{% content-ref url="/pages/-MekZq2SRW81pnLHnNb7" %}
[3. User Information](/feature-guides/authentication/web-application/3.-obtaining-authenticated-user-information-from-the-access-token)
{% endcontent-ref %}

{% content-ref url="/pages/-MekZzPtYuHMjOEPVU0A" %}
[4. Logout](/feature-guides/authentication/web-application/4.-web-single-sign-on-sso-and-logout-user-session-from-uae-pass)
{% endcontent-ref %}

{% content-ref url="/pages/-Mek\_67eDrqVa8jGV-WZ" %}
[User Linking](/feature-guides/authentication/user-linking)
{% endcontent-ref %}

{% content-ref url="/pages/-MkpUgEyh2UrTU0au9Hz" %}
[Login Button](/feature-guides/authentication/web-application/add-login-button)
{% endcontent-ref %}


# Introduction

This section explains how to integrate the web applications, allowing UAEPASS user to authenticate from third party web application.

Below is the high-level flow:

![Figure 2: High-level Flow](/files/-MekZOQA5B2pBkOCwCtn)

* As an enhancement to UAE PASS, **Visitors** will also be allowed to create verified profile and access services integrated with UAE PASS.
* SPs who will allow the Authentication for **Visitor** need to capture the response of a user profile from UAE PASS and depending on the attributes received, **SP needs to handle their business flow.**


# Pre-Requisites

* [x] Developer / Tester should have a user created on staging environment.
* [x] Staging mobile app installed on developer device.


# Endpoints

Since the integration is based on OAuth 2.0, below are the standard endpoints of UAE PASS for Staging and Production environment.

**Staging**

| Endpoint      | URL                                          |
| ------------- | -------------------------------------------- |
| Authorization | `https://stg-id.uaepass.ae/idshub/authorize` |
| Token         | `https://stg-id.uaepass.ae/idshub/token`     |
| User Info     | `https://stg-id.uaepass.ae/idshub/userinfo`  |
| Logout        | `https://stg-id.uaepass.ae/idshub/logout`    |

**Production**

| Endpoint      | URL                                      |
| ------------- | ---------------------------------------- |
| Authorization | `https://id.uaepass.ae/idshub/authorize` |
| Token         | `https://id.uaepass.ae/idshub/token`     |
| User Info     | `https://id.uaepass.ae/idshub/userinfo`  |
| Logout        | `https://id.uaepass.ae/idshub/logout`    |


# 1. Authorization Code

## Authorization Code Steps:&#x20;

### Step 1: Login page

#### For Standard Citizen/Resident Integration Flow:

Open the below URL to authenticate

```http
https://stg-id.uaepass.ae/idshub/authorize?response_type=code&client_id=sandbox_stage&scope=urn:uae:digitalid:profile:general&state=HnlHOJTkTb66Y5H&redirect_uri=https://stg-selfcare.uaepass.ae&acr_values=urn:safelayer:tws:policies:authentication:level:low 
```

#### For Visitor Integration:

SP need to use the below scopes to their first authentication call to retrieve the desired attributes of the user profile:

```
scope=urn:uae:digitalid:profile:general urn:uae:digitalid:profile:general:profileType urn:uae:digitalid:profile:general:unifiedId
```

Example:&#x20;

```
https://stg-id.uaepass.ae/idshub/authorize?redirect_uri=https://localhost:8080&client_id={client_id}&response_type=code&state=pd3PgezRwk596u2yfRwqOgru&scope=urn:uae:digitalid:profile:general urn:uae:digitalid:profile:general:profileType urn:uae:digitalid:profile:general:unifiedId&acr_values=urn:safelayer:tws:policies:authentication:level:low
```

### Step 2: Authenticate

Page will redirect to UAEPASS login page.&#x20;

![Figure 3: Login Page](/files/-Ml3dGmgXtHf705j48el)

### Step 3: Authorization Code

Provide the login identifier and confirm the push notification on the mobile. SP should use below code to pass to Access token Call. &#x20;

```
https://stg-selfcare.uaepass.ae/?code={Authorization Code}&state={State value}
```

{% hint style="success" %}
Note: Copy the **{Authorization Code}** to be used in next step to get the access token
{% endhint %}

**Response:**

```http
{your redirect_uri}?code={authorization_code}&state={state value}
```

## Authentication Request

<mark style="color:blue;">`GET`</mark> `https://stg-id.uaepass.ae/idshub/authorize`

Once the authentication of the user is complete, and the user has granted authorization, the application receives an HTTP GET request of the following type from the user’s browser. This HTTP request is an OAuth 2.0 authorization response. The application receives this request at the redirect URL specified in the authorization or authentication request message (the redirect\_uri parameter) or in the registered redirect URL.

#### Query Parameters

| Name           | Type   | Description                                                                                                                                                                                                                                                                                                                                                              |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| response\_type | string | Must take the value, which indicates that an code authorization code is requested.                                                                                                                                                                                                                                                                                       |
| redirect\_uri  | string | <p>Redirect URI to the application. </p><p>The application waits to receive at this URI the authorization or authentication response message with the authorization code.</p>                                                                                                                                                                                            |
| client\_id     | string | Identifier of the client application. (To be shared by UAEPASS Team)                                                                                                                                                                                                                                                                                                     |
| state          | string | We recommend using this parameter to safeguard against CSRF attacks. The application can also include additional information in this parameter, such as the URL to which the browser is to be redirected when the authorization or authentication finishes. (To include multiple data in the value of this parameter, the application must serialize it as it sees fit.) |
| scope          | string | List of values, separated by spaces, that represent the scope of the authorization that the application wants to obtain. It queries the scopes required for accessing the resources or services in question. (To be shared by UAEPASS Team if its value is other than specified in sample above)                                                                         |
| acr\_values    | string | Defines conditions for authenticating the user (minimum levels or specific flows) who must authorize the access. (To be used as specified in sample or check with UAEPASS team for more details)                                                                                                                                                                         |
| ui\_locales    | string | Language parameter to be sent to render English or Arabic login pages of UAEPASS and below are the possible values: English page : en Arabic page : ar                                                                                                                                                                                                                   |

{% tabs %}
{% tab title="200 " %}

```
GET {redirection_uri_path}?code={code}&state={state}
HTTP/1.1 Host: {redirection_uri_host}
```

{% endtab %}

{% tab title="302 " %}

```
```

{% endtab %}
{% endtabs %}


# 2. Access Token

As per the diagram shown in [figure 2](/feature-guides/authentication/web-application/introduction), SP should obtain the access token by passing the same authorization code which was received in the [previous step](/feature-guides/authentication/web-application/1.-obtaining-the-oauth2-access-code).&#x20;

### cURL Request for Token Generation Call

```css
curl --location --request POST 'https://stg-id.uaepass.ae/idshub/token?grant_type=authorization_code&redirect_uri=https://stg-selfcare.uaepass.ae&code=bfe96299-83f4-3ee9-80e4-56c24f5265d3' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Basic c2FuZGJveF9zdGFnZTpzYW5kYm94X3N0YWdl'
```

{% hint style="warning" %}
Replace code parameter '**{ code}**' with the value received from [**Authorization Code.**](/feature-guides/authentication/web-application/1.-obtaining-the-oauth2-access-code)&#x20;
{% endhint %}

### Response

```json
{
  "access_token": "67f2536e-07e6-37c1-967f-78562000a4f9",
  "scope": "urn:uae:digitalid:profile:general",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

## API detail to exchange the token

<mark style="color:green;">`POST`</mark> `https://stg-id.uaepass.ae/idshub/token`

#### Query Parameters

| Name          | Type   | Description                                                                                                                                                     |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| grant\_type   | string | Must have the value as “authorization\_code”.                                                                                                                   |
| redirect\_uri | string | Redirect URI to the application. The application waits to receive at this URI the authorization or authentication response message with the authorization code. |
| code          | string | Authorization code received in the previous authorization response.                                                                                             |

#### Headers

| Name          | Type   | Description                        |
| ------------- | ------ | ---------------------------------- |
| Authorization | string | Basic {credentials}                |
| Content-Type  | string | multipart/form-data; charset=UTF-8 |

{% tabs %}
{% tab title="200 In response, UAEPASS issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.
JSON object containing the access token, associated information and (if the scope was openid requested) an ID token.

access\_token: Access token generated by UAE PASS.
token\_type: Type of access token. Always has the “Bearer” value.
expires\_in: Lifetime (in seconds) of the access token.
scope: Scopes granted to those to which the access token is associated, separated by spaces." %}

```json
{
  "access_token": "67f2536e-07e6-37c1-967f-78562000a4f9",
  "scope": "urn:uae:digitalid:profile:general",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

{% endtab %}

{% tab title="400 invalid\_client, unregisteredClient: The client application is not registered. This error is usually observed due to misconfiguration of client credentials.
unsupported\_grant\_type: The value of the grant\_type parameter in the request is not supported. TrustedX currently only supports the authorization\_code type.
invalid\_grant, codeNotFound: The authorization code specified in the code parameter of the request was not issued in a recent authorization response or has expired.
invalid\_grant, expiredCode: The authorization code specified in the code parameter of the request has expired. This error appears when passing the expired code to token generation call. The auth code received from authorization url should be utilized by SP within 10 seconds.
invalid\_grant, codeNotIssuedToClientId: The authorization code specified was issued for a different client application than that identified in the Authorization HTTP header.
invalid\_grant, redirectUriMismatch: The authorization code specified was issued for an authorization request associated to a redirect URL different from the URL specified in the redirect\_uri parameter of the request. Please make sure that SP passes the same redirect url in authentication and token generation calls.
invalid\_grant, invalidOrExpiredCode: The authorization code specified in the code parameter of the request has expired or invalid.
invalid\_scope: Only for the client credentials grant flow. One of the scopes requested by the application is not included in this list of scopes provided by the authorization server or has not been enabled for the client credentials grant. This error also occurs if the application did not request any scope and the server has no default scope defined for this type of grant.
Invalid\_basic\_header\_authentication: This error appears when SP is not passing the client id or secret properly as configured in server.
Invalid\_Token: Please make sure that SP is passing the token to user profile API using header Authorization as Bearer {token}. " %}

```json
{
  "error": "Error code",
  "error_description": "invalidHttpBasicAuthenticationToken"
}
```

{% endtab %}

{% tab title="401 invalid\_client, unsupportedAuthenticationScheme: The authentication scheme specified in the Authorization HTTP header is not supported. TrustedX currently only supports the basic scheme (HTTP Basic authentication scheme) specified in RFC 2617.
invalid\_client, invalidCredentials: The client application cannot be authenticated with the credentials included in the Authorization HTTP header. This may be because there is no Client Application configured in TrustedX with the identifier specified or because the entity exists but the secret does not match the configured secret. " %}

```json
{
  "error": "Error code",
  "error_description": "Additional description of the error"
}
```

{% endtab %}

{% tab title="500 If an internal error occurred in the server, a JSON response is not returned. Instead, an HTTP 500 (Internal Server Error) status code is returned In these cases, the TrustedX administrator must browse the log records to identify the problem." %}

```json
{
  "error_description": "description"
}
```

{% endtab %}
{% endtabs %}


# 3. User Information

### cURL Request for User Information

```bash
curl --location --request GET 'https://stg-id.uaepass.ae/idshub/userinfo' \
--header 'Authorization: Bearer {Access Token}'
```

{% hint style="warning" %}
Replace code parameter '**{Access Token}**' with the value received from **Step 2**
{% endhint %}

### **Response(Citizen/Resident Profile)**

```json
{
    "sub": "UAEPASS/7a05992e-3244-49d3-bcbc-7894c8fca25e",
    "fullnameAR": "ساوميا,,,,شارما,,",
    "gender": "Male",
    "mobile": "97151234003",
    "lastnameEN": "ABC",
    "fullnameEN": "Ram,,,,ABC,,",
    "uuid": "7a05992e-3244-49d3-bcbc-7894c8fca25e",
    "lastnameAR": "شارما",
    "idn": "784189014978983",
    "nationalityEN": "IND",
    "firstnameEN": "Ram",
    "userType": "SOP3",
    "nationalityAR": "هندى",
    "firstnameAR": "ساوميا",
    "email": "ramabc1234@gmail.com"
}

```

### **Response(Visitor Profile)**

{% hint style="info" %}

```json
{
   "sub": "35q00600-27a0-5555-8d93-453392902b84",
   "fullnameAR": "عمر,بدوى,حسنين,,عبدالله,,",
   "mobile": "971566612311",
   "fullnameEN": "AMAR,,,,KHAN,,",
   "uuid": "35q87600-27a0-5555-8d93-453392902b84",
   "profileType": "2",
   "nationalityEN": "IND",
   "nationalityAR": "هندى",
   "firstnameEN": "AMAR",
   "unifiedID": "123458099",
   "userType": "SOP3",
   "firstnameAR": "عمر",
   "lastnameAR": "شارما",
   "lastnameEN": "Khan",
   "email": Khan@dubai.ae
}
```

{% endhint %}

## API Details

<mark style="color:blue;">`GET`</mark> `https://stg-id.uaepass.ae/idshub/userinfo`

#### Headers

| Name                                            | Type   | Description                                     |
| ----------------------------------------------- | ------ | ----------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer {access token received in previous step} |

{% tabs %}
{% tab title="200 This response may change as per the scope and list of attributes allowed to share with your application" %}

```json
{
  "sub": "800F475AC0E7A9ED01B2D5D2C25A59B3",
  "userType": "SOP3",
  "fullnameAR": "سميث جون",
  "fullnameEN": "John Smith",
  "gender": "Male",
  "lastnameEN": "Smith",
  "nationalityAR": "الهند",
  "firstnameEN": "John",
  "idn": "784000000000000",
  "idType": "ID",
  "email": "john.smith@organization.com",
  "spuuid": "b1320896-fb2e-5140-baf0-fa915eb9be5d",
  "nationalityEN": "IND",
  "firstnameAR": "جون",
  "lastnameAR": "سميث",
  "acr": "urn:safelayer:tws:policies:authentication:level:high",
  "mobile": "9715555555555",
  "titleEN": "Dr.",
  "titleAR": ".د",
  "amr": [
    "urn:safelayer:tws:policies:authentication:adaptive:methods:mobileid",
    "urn:uae:authentication:method:verified"
  ]
}
```

{% endtab %}
{% endtabs %}

### Step 2 and 3 are shown pictorially below as sequence diagram:

![Figure 6: Access Token](/files/-MekZxVy5U5Cxaq4fO6z)

**SOP Handling for Visitor Profile**

<figure><img src="/files/uWWA93UJzle9WsYXg9of" alt=""><figcaption></figcaption></figure>


# 4. Logout

To logout from UAEPASS, use the following logout URL.

```
https://stg-id.uaepass.ae/idshub/logout?redirect_uri=https://stg-selfcare.uaepass.ae
```

{% hint style="warning" %}
redirect\_uri should be replaced by URL of Relying party where the response will be sent after logout from UAEPASS.

In case additional parameter has to be passed in logout redirect\_uri, then encoded value of redirect\_uri to be passed."
{% endhint %}

{% hint style="danger" %}
Note: Service Provider should make sure to logout the user from UAEPASS when user clicks on Logout from Service Provider Web Portal.
{% endhint %}


# Login Button

{% file src="/files/-Ml3kQnakghDan2IUWK-" %}
&#x20;Login Buttons in SVG Format
{% endfile %}

{% file src="/files/-Ml3kU\_\_uL34eg4vx5fm" %}
Login Buttons in PNG Format
{% endfile %}

{% file src="/files/-Ml3kZs8GqfeWctpz5UT" %}
Buttons Guidelines
{% endfile %}

{% file src="/files/-Ml3kbkSSUXnUIp-swYG" %}
UAEPASS Buttons
{% endfile %}

{% file src="/files/-Ml3kMknCXO1yUmTDoVu" %}
Sign In with UAEPASS Buttons&#x20;
{% endfile %}


# Authentication Postman Walkthrough

{% file src="/files/zQuGZUGofK9NcQcPfRQv" %}


# Mobile Integration

### Here are the articles in this Section:

{% content-ref url="/pages/-Mek\_JNWsMsA-A12xkQq" %}
[Introduction](/feature-guides/authentication/mobile-application/introduction)
{% endcontent-ref %}

{% content-ref url="/pages/-Mek\_LTtsTsShLq4jCeM" %}
[Pre-Requisites](/feature-guides/authentication/mobile-application/pre-requisites)
{% endcontent-ref %}

{% content-ref url="/pages/-Mek\_Ps7\_-f7RZ-rMDGF" %}
[Requirements](/feature-guides/authentication/mobile-application/requirements)
{% endcontent-ref %}

{% content-ref url="/pages/74pqH2vgH5XeE7LNsIQU" %}
[Guide](/feature-guides/authentication/mobile-application/guide)
{% endcontent-ref %}

{% content-ref url="/pages/-Mkkwg0JkvWckuuxrChF" %}
[Authentication Postman Walkthrough](/feature-guides/authentication/web-application/authentication-postman-walkthrough)
{% endcontent-ref %}

{% content-ref url="/pages/-MkkwkC5uUFZbq0uKVVR" %}
[Broken mention](broken://pages/-MkkwkC5uUFZbq0uKVVR)
{% endcontent-ref %}


# Introduction

If the application installed is a mobile application, additional steps are required to support the integration with the UAEPASS Mobile ID application.&#x20;


# Pre-Requisites

* [x] The installed application is an Android or iOS mobile application.
* [x] The installed application uses a Web View for integrating the OAuth 2.0 flow (not the system's browser).&#x20;

{% hint style="warning" %}
In this type of integration, the Web View cannot interact with other mobile applications in the system (only with UAEPASS mobile app). This means that UAEPASS App should only open when the identity provider specifies in the WebView.&#x20;

The application must intercept the UAE PASS Mobile ID callback URL and load it in the WebView. Otherwise, after the interaction with Mobile ID has finished, the system's browser would open. Also, the SP application must use its own URI scheme.
{% endhint %}


# Requirements

The mobile application (yourapp) must be programmed to perform the following tasks:

1. Register during installation, its own customized URI scheme (e.g., yourapp\://...) in the mobile's operating system.
2. Start OAuth 2.0 authorization (or OpenID Connect authentication) with UAEPass in the WebView.
3. Monitor the WebView's URL to intercept the Mobile ID's URI scheme (by default,mobileid://...).
4. In the Mobile ID's URI, change the callback URLs so they use the URI scheme of your app instead of https, propagating the original callback URL via a parameter.
5. Launch the Mobile ID application, opening the modified URI in the system.
6. Process incoming URLs that use the customized scheme (yourapp\://...), retrieving the original callback URL from the parameter.
7. Open the original callback URL in the WebView so the authorization server can take over again and complete the OAuth authorization.
8. Monitor the WebView URL to intercept the OAuth redirect URI, which indicates the completion of the authorization phase.

{% hint style="info" %}
**Note**: See the documentation for the mobile's operating system for how to perform these tasks, in particular the communication between applications using customized URI schemes.
{% endhint %}

{% hint style="danger" %}
Make sure to use your own app scheme instead of **uaepassdemoapp\://** in both Staging and Production environment in order avoid app redirection issues from your app to other service provider apps.
{% endhint %}


# Guide

### The Mobile Integration can be done through API:

{% content-ref url="/pages/MJohsUVY9kJDdA2X4tVu" %}
[API](/feature-guides/authentication/mobile-application/guide/api)
{% endcontent-ref %}


# API

**Android:** check whether UAEPASS app is installed or not by using UAEPASS package **id: ae.uaepass.mainapp.stg**

**iOS:** check whether UAEPASS app is installed or not by using UAEPASS scheme: Production: uaepass\:// , Staging: uaepassstg://

### **App installed scenario:**

1. If the app is installed in the mobile, then invoke the Login url with acr values: acr\_values=urn:digitalid:authentication:flow:mobileondevice
2. Invoke the login url in embedded webview

```
// httpsdfa:Fasdfadsf
```

{% embed url="<https://stg-id.uaepass.ae/idshub/authorize?acr_values=urn%3Adigitalid%3Aauthentication%3Aflow%3Amobileondevice&client_id=sandbox_stage&redirect_uri=https%3A%2F%2Fstg-selfcare.uaepass.ae&response_type=code&scope=urn%3Auae%3Adigitalid%3Aprofile%3Ageneral&state=ShNP22hyl1jUU2RGjTRkpg%3D%3D>" %}
&#x20;                                                       &#x20;
{% endembed %}

&#x20; 4\. Monitor the webview for UAEPASS deep linking url as below:

```
uaepassstg://...? successURL=<url1> & failureURL=<url2> & ...                           
```

5\. Save the success url and failure url in separate variables.

6\. Re-write the deeplinking url by changing the success url and failure url with SP app scheme and host.

```
uaepassstg://...?successURL=yourapp:///resume_authn?url=<url1>&failureURL=yourapp:///resume_authn?url=<url2> & ...                                               
```

7\. Invoke the above url in the same webView to open the UAEPASS app for authentication. Once the user confirms the authentication, SP will receive the callback from UAEPASS as successURL. if user cancels the authentication, SP will receive failureURL.

8\. Once SP receives callback, SP should invoke the successURL which is stored previously within the same webView.

9\. SP will then receive the access code.

10\. Access token call (copy and paste the same from web integration).

11\. Get user info: (copy and paste the same from web integration).&#x20;

### **App not installed scenario:**

1\. if UAE Pass app is not found in the mobile, SP should use the Login url with acr:

```
values :acr_values=urn:safelayer:tws:policies:authentication:level:low
```

2\. Invoke the login url in embedded webview

> &#x20;<https://stg-id.uaepass.ae/idshub/authorize?response_type=code&client_id=sandbox_web_stage&scope=urn:uae:digitalid:profile:general&state=HnlHOJTkTb66Y5H&redirect_uri=https://stg-selfcare.uaepass.ae&acr_values=urn:safelayer:tws:policies:authentication:level:low>

{% embed url="<https://stg-ids.uaepass.ae/authenticationendpoint/oauth2_error.do?oauthErrorCode=invalid_client&oauthErrorMsg=Cannot+find+an+application+associated+with+the+given+consumer+key+%3A+sandbox_web_stage>" %}

3\. User has to provide his UAE PASS identifier (email, mobile and emirates ID) and click on login.

4\. User will receive push notification on other device which has UAE PASS app installed.

5\. Once the user confirms the authentication, SP will receive the access code in webview.

6\. Access token call (copy and paste the same from web integration).

7\. Get user info (copy and paste the same from web integration).

{% hint style="info" %}
**For visitor integration:** SP need to use the below scopes to their first authentication call to retrieve the unifiedID and profileType attribute of the user:&#x20;

```
 scope=urn:uae:digitalid:profile:general urn:uae:digitalid:profile:general:profileType urn:uae:digitalid:profile:general:unifiedId
```

{% endhint %}


# SDK

UAE Pass Demo App is a sample app to show you how to use UAE Pass for.

* App to app login.
* Login with WebView inside the app .. incase if UAE Pass not installed in the same device.
* Getting user profile details.
* Download smaple document.
* Sign donwnloaded document.
* View signed document.


# iOS

**1- Framework setup**

* Create LocalPods folder if you don't have it.
* Add UAEPPASSClient folder in LocalPods folder.
* Add pod 'UAEPassClient', :path => "LocalPods/UAEPassClient" to your podfile

**2- Should do**

* In AppDelegate add below : import UAEPassClient
* In didFinishLaunchingWithOptions add&#x20;

```
UAEPASSRouter.shared.spConfig = SPConfig(redirectUriLogin: "client redirect url",
                                         scope: "client login scope",
                                         state: "RANDOM 24 alpha numeric",  //Randomly Generated Code 24 alpha numeric.
                                         successSchemeURL: "UUUUU://", //client success url scheme.
                                         failSchemeURL: "CCCCC://", //client failure url scheme.
                                         signingScope: "urn:safelayer:eidas:sign:process:document") // client signing scope
                                         UAEPASSRouter.shared.environmentConfig = UAEPassConfig(clientID: "your client id", env: .production)
--- env (environment can be : .production or .stg)
```

* func application(\_: UIApplication, handleOpen url: URL) -> Bool

```
print("<><><><> appDelegate URL : \(url.absoluteString)")
    if url.absoluteString.contains(HandleURLScheme.externalURLSchemeSuccess()) {
        if let topViewController = UserInterfaceInfo.topViewController() {
            if let webViewController = topViewController as? UAEPassWebViewController {
                webViewController.forceReload()
            } 
        }
        return true
    } else if url.absoluteString.contains(HandleURLScheme.externalURLSchemeFail()) {
        guard let webViewController = UserInterfaceInfo.topViewController() as? UAEPassWebViewController  else { return false}
        webViewController.foreceStop()
        let alertController = UIAlertController(title: "Failed to login with UAE PASS Login", message: "Try again later", preferredStyle: .actionSheet)
        let okAction = UIAlertAction(title: "OK", style: UIAlertAction.Style.default) { _ in
            NSLog("OK Pressed")
            webViewController.navigationController?.popViewController(animated: true)
        }
        alertController.addAction(okAction)
        self.window?.rootViewController?.present(alertController, animated: true, completion: nil)
        return false
    }
    return true
}
```

**3- Should do**

* Add UAE Pass scheme in your project info.plist in LSApplicationQueriesSchemes (Already added in this sample): --  -- **Production**: uaepass\
  \-- **STG**: uaepassstg

**For more understanding:**

**Authentication**

* After press on login with UAE PASS button you will be asked to select which environment you would like to use for login through UIAlertController and from this action you can trace how it works.
* from application(\_: UIApplication, handleOpen url: URL) -> Bool in AppDelegate you can force current web view to reload or stop loading incase if success or failure.
* This sample contains three view controllers : -&#x20;

1. \-- ViewController.swift (main screen which contains login button and UIAlertController to select required environment).
2. UserProfileViewController.swift (Just simple view to show user profile details and it contains sign document scenario as well).
3. UAEPassWebViewController.swift (Resposible for handling webView requests to generate UAE PASS code to use it for token generation).

**Signing flow** :

* you should have valid pdf file and in this sample you will be able to see sample code for downloading pdf file.
* Then we have to generate valid token for signing process from your server
* Your backend must fetch this token using your `CLIENT_ID` and `CLIENT_SECRET` and return it to the app.
* **This is NOT the same token used for authentication.**
* Then we have to upload above valid pdf document to UAE PASS.
* After uploading we have to send our request for signing for (signature type (advanced or qualified), on which page signature will be placed, signature coordinates and signature size)

**Check**&#x20;

* testSignData.json is very important file as this is signing info which you should pass to UAE Pass app and it's expected to be received from the back end and it's required to be reconfigured to add your own app scheme

**Note : This sample supports dark mode as well**


# Android

**Quick Setup**

1. Open `SampleApp/` in Android Studio.
2. Ensure the library exists at:
   * `SampleApp/app/libs/UAE-PASS-Android-Library-release.aar`
3. Verify `SampleApp/app/build.gradle` includes:
   * `implementation files('libs/UAE-PASS-Android-Library-release.aar')`
4. Configure your values in `SampleApp/app/build.gradle`:
   * `CLIENT_ID`
   * `CLIENT_ID_FACE_VERFICATION`
   * `REDIRECT_URL`
   * `URI_SCHEME` (must be unique; do not keep the sample value)
5. Make sure `manifestPlaceholders.scheme` matches `URI_SCHEME`.

**#Mandatory First Flow (Do This First)**

**Before profile or signing actions, complete this sequence:**

1. Select environment in the app ( `STAGING`, `PRODUCTION`).
2. Tap **Get Access Code**.
3. Send the returned access code to your backend.
4. Backend exchanges code for token and returns token to app.
5. Paste token in the **Access Token** field.
6. Tap **Submit Access Token**.

**Environment Mapping**&#x20;

The selected environment must match the UAE Pass app installed on the device:

* `PRODUCTION` -> `ae.uaepass.mainapp`
* `STAGING` -> `ae.uaepass.mainapp.stg`

\#***Use the correct token for each operation.***

#### 1) User Access Token (Profile)

* Obtained by backend after exchanging login access code.
* Used for profile retrieval (`getUserProfile`).

#### 2) Signing Token (Client Credentials)

* Obtained by backend using client credentials and signing scope.
* Used for document signing and signed-document download.
* This token is different from the profile/user token.

### Get User Profile

After submitting a valid **User Access Token**:

1. Tap **Get User Profile**.
2. App calls `UAEPassController.getUserProfile(...)`.

### Document Signing Flow

#### Prerequisites

* Use sample PDF from assets (`dummy.pdf`) or your own PDF.
* Ensure signing payload JSON is valid.
* Ensure signing token is pasted and submitted.

#### Signing Steps

1. Paste signing token in **Access Token** field.
2. Tap **Submit Access Token**.
3. Tap one of:
   * **Sign Document** (advanced)
   * **Sign Document (Qualified)**
4. Complete UAE Pass authentication in app or WebView.
5. App receives `documentURL` in callback.
6. App downloads signed PDF via `downloadDocument(...)` and saves it to Downloads.

### Signing Payload Files

* `SampleApp/app/src/main/assets/testSignData.json`
* `SampleApp/app/src/main/assets/testSignDataQualified.json`

Ensure `finish_callback_url` matches your app scheme:

```json
"finish_callback_url": "yourappscheme://sign"
```

For qualified signature flow, use `testSignDataQualified.json`.

### Reset / Logout

Use the **Reset** button to clear local session data:

* Clears stored access token (`UAEPassController.clearAccessToken()`)
* Clears WebView cookies
* Clears token input and access code label in UI

### Run the Sample

From project root `SampleApp/`:

```zsh
./gradlew clean
./gradlew assembleDebug
```

Then install and run from Android Studio or with ADB.

**Main Files to Review**

* `SampleApp/app/src/main/java/ae/sdg/uaepasssample/MainActivity.kt`
* `SampleApp/app/src/main/java/ae/sdg/uaepasssample/UAEPassRequestModels.kt`
* `SampleApp/app/src/main/assets/testSignData.json`
* `SampleApp/app/src/main/assets/testSignDataQualified.json`
* `TECHNICAL_DOCUMENTATION.md`

<mark style="color:$success;">**Note :**</mark>&#x20;

* Submit Access Token does not call UAE Pass APIs.
* It only stores the token using `UAEPassController.setAccessToken(...)` for later calls.


# Token Validation API

This describes the API to be used by intended SPs in order to validate/verify the token issued by UAEPASS system.

The Audience of this documentation is those who want to integrate with this API using REST standards. This document describes the operations available and the corresponding input and output parameters when invoking these operations.

### Here are the articles in this Section:

{% content-ref url="/pages/-Mkfk2Ln2aSQ2OnDiMrG" %}
[Introduction](/feature-guides/authentication/token-validation-api/introduction)
{% endcontent-ref %}

{% content-ref url="/pages/-MkfkkRBl47CAPwpsEM-" %}
[Pre-Requistes](/feature-guides/authentication/token-validation-api/pre-requistes)
{% endcontent-ref %}

{% content-ref url="/pages/-MkflBU39HcMER-9FouB" %}
[Endpoints](/feature-guides/authentication/token-validation-api/endpoints)
{% endcontent-ref %}

{% content-ref url="/pages/-MkfmMECQQ1-e3yluEYs" %}
[Integration Steps](/feature-guides/authentication/token-validation-api/integration-steps)
{% endcontent-ref %}

{% content-ref url="/pages/-Mkg0bO2vmKhXIMzxHw5" %}
[Validation Decisions](/feature-guides/authentication/token-validation-api/validation-decisions)
{% endcontent-ref %}


# Introduction

This API or operation is designed for the clients that act as a Resource Server (for e.g. GSB or middleware API layer) who use this operation to verify a token that another client obtained and submitted to this Resource Server for accessing the resources (e.g. APIs) controlled by it.&#x20;

This operation indicates if an OAuth 2.0 access token is active and, if it is, returns the token's metadata. This operation implements the token introspection (verification) protocol defined in RFC 6662 - OAuth 2.0 Token Introspection.

Below is the high-level flow:

![Figure 9: Token Validation](/files/-MkfkcYTpu6_fDZEaZBP)


# Pre-Requistes

* [x] For new SPs : Obtain the client credentials from UAE PASS team for using this validation API.
* [x] For already integrated SPs : Request UAE PASS team to allow access to token validation API.


# Endpoints

Since the integration is based on OAuth2, below are the standard endpoints of UAEPASS for STG and Production environment:

**Staging**

| Endpoint  | URL                                                                                  |
| --------- | ------------------------------------------------------------------------------------ |
| Token     | `https://stg-id`.uaepass.ae/idshub/introspect                                        |
| User Info | [`https://stg-`id.uaepass.ae/idshub/userinfo](https://id.uaepass.ae/idshub/userinfo) |

**Production**

| Endpoint  | URL                                                                                  |
| --------- | ------------------------------------------------------------------------------------ |
| Token     | [`https://id.uaepass.ae/idshub/introspect`](https://id.uaepass.ae/idshub/introspect) |
| User Info | [`https://`id.uaepass.ae/idshub/userinfo](https://id.uaepass.ae/idshub/userinfo)     |


# Integration Steps

### The following entails 2 steps:&#x20;

{% content-ref url="/pages/-Mkfm\_2lRdcUMWUn6YVF" %}
[1. Verify access token API using Basic Authentication](/feature-guides/authentication/token-validation-api/integration-steps/1.-obtaining-resource-server-or-sp-access-token)
{% endcontent-ref %}

{% content-ref url="/pages/-MkfseXFX6\_mCOqkXloX" %}
[2. Obtaining Authenticated User Information from the Access Token](/feature-guides/authentication/token-validation-api/integration-steps/2.-verifying-access-token-api)
{% endcontent-ref %}

**Note:** In case if SP is using introspect API with older version, they need to use the new API. Basically, in old version two API’s are called to introspect the token. However, in new version it can be done by using single API as below using Basic Authentication.


# 1. Verify access token API using Basic Authentication

Obtaining Resource Server (or SP) Access Token

As per the diagram shown in [Figure 9](/feature-guides/authentication/token-validation-api/introduction), the resource server SP needs to obtain the access token before verifying the token of client app. Below here is the API detail to obtain the token:

### cURL Request for Token Generation Call

```
curl --location --request POST 'https://stg-id.uaepass.ae/idshub/introspect' \
--header 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
--header 'Authorization: Basic <<Basic auth credentials>>' \
--header 'Cookie: NSC_EJE_TUBH_USVTUY_MC_8082=ffffffffaf1a571d45525d5f4f58455e445a4a4229a2' \
--data-urlencode 'token=<<Token to introspect>>
```

## API detail to verify the Token

<mark style="color:green;">`POST`</mark> `https://stg-id.uaepass.ae/idshub/introspect`

#### Path Parameters

| Name  | Type  | Description                          |
| ----- | ----- | ------------------------------------ |
| token | query | Access token of Client App to verify |

#### Headers

| Name          | Type   | Description                                      |
| ------------- | ------ | ------------------------------------------------ |
| Content-Type  | string | Application/x-www-form-urlencoded; charset=UTF-8 |
| Authorization | string | Basic {**base64 format of client credentials**}  |

{% tabs %}
{% tab title="400: Bad Request Invalid token response" %}

```json
{
  {"active":false,}
}
```

{% endtab %}

{% tab title="200: OK Valid token response" %}

```javascript
{
    "sub": "sample_web_stage",
    "nbf": 1633262176,
    "scope": "internal_application_mgt_view",
    "iss": "https://qa-ids.uaepass.ae:443/oauth2/token",
    "client_claims": {
        "sub": "sample_web_stage",
        "acr": "",
        "domain": "urn:safelayer:eidas:domain:oauth:client",
        "amr": "",
        "distinguished_name": "Sample Web Application",
        "name": "Sample Web Application"
    },
    "active": true,
    "token_type": "Bearer",
    "exp": 1633265776,
    "iat": 1633262176,
    "client_id": "sample_web_stage",
    "username": "admin@carbon.super"
}

```

{% endtab %}
{% endtabs %}

**Response Parameter Details:**

| Name            | Description                                                                                                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| active          | True if the token is valid (issued by TrustedX and not expired); false otherwise. When this property is false, it is the only property in the response.                       |
| token\_type     | Type of access token. Always has the “Bearer” value.                                                                                                                          |
| scope           | Scopes granted to those to which the access token is associated, separated by spaces.                                                                                         |
| exp             | When the token expires, expressed as the number of seconds from 1 January 1970 (UTC).                                                                                         |
| iat             | When the token was issued, expressed as the number of seconds from 1 January 1970 (UTC).                                                                                      |
| iss             | Token issuer.                                                                                                                                                                 |
| client\_id      | Client identifier of the OAuth 2.0 application registered in UAE PASS for which the token was issued.                                                                         |
| client\_claims  | Attributes of the client application and information on how it was authenticated by UAEPASS.                                                                                  |
| sub             | User identifier.                                                                                                                                                              |
| user\_claims    | Claims of the user.                                                                                                                                                           |
| times\_verified | Number of times that the token had been previously verified, without including the current verification. The first time a token is verified, this field takes the value of 0. |


# 2. Obtaining Authenticated User Information from the Access Token

The SP can validate the access token based on the information obtained in previous step. In case the SP needs to know the user who is authenticated with the presented access token then it can also fet

### cURL Request&#x20;

```
curl --location --request GET 'https://stg-id.uaepass.ae/idshub/userinfo' \
--header 'Authorization: Bearer <<Token to get the authenticated user profile>>'
```

## API detail to get user info

<mark style="color:blue;">`GET`</mark> `https://stg-id.uaepass.ae/idshub/userinfo`

#### Headers

| Name                                            | Type   | Description                                                            |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {access token received from client app or required to validate} |

{% tabs %}
{% tab title="200: OK Note: This response may change as per the scope and list of attributes allowed to share with client application" %}

```javascript
{
"sub": "800F475AC0E7A9ED01B2D5D2C25A59B3",
…
…………
………… "acr":
"urn:safelayer:tws:policies:authentication:level:high", "mobile": "9715555555555",
"amr": [ "urn:safelayer:tws:policies:authentication:adaptive:methods:mobileid", "urn:uae:authentication:method:verified"
] }
```

{% endtab %}
{% endtabs %}


# Validation Decisions

#### As per [above section](/feature-guides/authentication/token-validation-api/integration-steps), SP might have invoked the validation API and below are some guidelines on how to make decision on token validation response.

#### Based on the response from earlier section, “[Verify Access Token](/feature-guides/authentication/token-validation-api/integration-steps/2.-verifying-access-token-api)” and “[Obtain User information API](broken://pages/-Mkg-h9NOVvq2u0kpZss)”, SP should check below in chronological order:

1.**(Mandatory)** As per response of “Verify Access Token” API, If the token is not active i.e. active=false, then the resource server or SP should deny access to the resource.

2.**(Mandatory)** If the SP wants to verify if the token presented is issued by a particular client, then it should verify the value of “client\_id” or the values available under “client\_claims” from the response of “Verify Access Token” API.

* For example, if SP wants to validate that the token presented is issued by “SDG Digital Vault App” then it should check below values:

```xml
"client_id":"sdg_digivault",
"client_claims": 
{
    "distinguished_name":"CN=SDG DigitalVault",
    "sub":"sdg_digitalvault",
    "name":"SDG Digital Vault App",
    "domain":"urn:safelayer:eidas:domain:oauth:client",
    "acr":"urn:safelayer:tws:policies:authentication:level:low",
    "amr":"["urn:oasis:names:tc:SAML:1:0:am:password"]
}
```

3.**(Optional but recommended)** If SP needs to determine the "uuid" of the user who has been authenticated with the presented access token, then it should check the value of "*sub*" attribute returned in "Verify Access Token" API response.

* For example, SP needs to get the "uuid" of the authenticated user as per below:

```svg
{
"sub": "800F475AC0E7A9ED01B2D5D2C25A59B3",
…
…………
………… 
"acr":
"urn:safelayer:tws:policies:authentication:level:high", 
"mobile": "9715555555555",
"amr": [ "urn:safelayer:tws:policies:authentication:adaptive:methods:mobileid", "urn:uae:authentication:method:verified"] 
}
```

4.**(Optional but recommended)** If SP needs to fetch the claims or attributes (e.g. Emirates ID etc.) of the user belonging to the access token, then SP should invoke “User information API” as mentioned in[ previous Section](broken://pages/-Mkg-h9NOVvq2u0kpZss).&#x20;

* For example: SP needs to get the Emirates ID of the authenticated user, then they should call "User information API" and validate the attributes returned in the response.

5.**(Optional)** If SP needs to make sure that the presented access token is issued for a particular scope, in order to decide whether to provide access or not, then it should check the value of the “scope” parameter in the validation token response.

```
{
    "active": true, 
    "scope": 
    "urn:uae:digitalid:profile:general", "exp":
}
```


# User Linking

{% content-ref url="/pages/kRCYzBJWGHjbhRWefE79" %}
[Automatic Linking](/feature-guides/authentication/user-linking/automatic-linking)
{% endcontent-ref %}

{% content-ref url="/pages/y0QZFpLOztxKGYni2yJi" %}
[Manual Linking](/feature-guides/authentication/user-linking/manual-linking)
{% endcontent-ref %}

{% content-ref url="/pages/xjteXbbz8qNaVxf74zbs" %}
[Corporate Account](/feature-guides/authentication/user-linking/corporate-account)
{% endcontent-ref %}

## UAEPASS User Linking Flow

![User Linking Flow](/files/-MlJYRc8w4YUFU5OdG8Q)

## Use Cases

We are detailing here few use cases and SP can handle accordingly:

### **Use Case 1** &#x20;

User logged in using his UAEPASS Account and the user is having an existing account in SP application, then allow the user to connect its SP user account with UAEPASS account {Integrating parties should support two modes as applicable.}

#### **Automatic Linking**

In case **Automatic Accounts Linking** is adopted "this is applicable if the relying party maintains the IDNnumber of the Emirates ID (or any other common attributes) for local users and in this case the link happens depending on the IDN."

Other attributes like date of birth, passport number or any shared attribute between the User Profile in UAEPASS and Relying Party are also recommended to be used to uniquely identify user if applicable.

{% hint style="warning" %}
**Note**: For linking, it is recommended to use “uuid” attribute returned by UAEPASS for user linking purposes for subsequent visits.
{% endhint %}

#### **Manual Linking**

In case **Manual Linking** is adopted, the user should be challenged by the Relying Party application with his Relying Party's account username and password (or any other authentication mechanism) and on successful authentication, the linking can be achieved by storing the linking attributes (e.g.uuid, idnetc.) at Relying Party side. This is one time activity and should be done only on first linking attempt.

{% hint style="warning" %}
**Note**: For linking, it is recommended to use “uuid” attribute returned by UAEPASS for user linking purposes for subsequent visits.
{% endhint %}

### **Use Case 2**

User has logged in using his UAEPASS Account and the user is non-existing user in Relying Party application, then allow the user to register and create account using the User Information retrieved from UAEPASS.

#### **Auto Populate Form**

User is creating an account with entity and he has not logged in using UAEPASS, entity should give the end user the option to auto populate entity User Form using the UAEPASS Authentication Service.

#### **Register using UAE PASS option**

UAEPASS can be used to populate Local User Registration Form for Relying Party Registration.

### **Use Case 3**

On Successful authentication at UAEPASS, the control is sent back to SP irrespective of user type. The SP should handle the authorization or flow at their end as per the user types and their business.

{% hint style="info" %}
**SOP1 :** In case of SOP1, UAEPASS will not return the Emirates ID number attribute as the user has still not verified his/her emirates ID at this stage. SP should handle such case by showing an appropriate error message to SOP1 Users.&#x20;
{% endhint %}


# Automatic Linking

UAE Pass UUID or Emirates ID should be used to link the user. The service provider should maintain a reference to either values to allow the user to login.

Other attributes should always be compared & updated at every login in the service provider system as they can be changed by the user at anytime.

{% hint style="danger" %}
Note: Linking should be done based on **UUID** and **Emirates ID** only, since UAEPASS provides an option to change the Email and Mobile in UAEPASS account.&#x20;
{% endhint %}

| Local Account                                                                                                                                                   | User Profile | Action                                                                                                                                                                                                                                              |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>Account Linking (One time activity) </p><p><strong>1 Record is Found</strong></p><p>Auto matching the user formation between UAE Pass and local account.</p> | SOP 1, 2, 3  | <p>Link user with UAEPASS using one of the unique key attributes (SPUUID, EID)</p><p></p><ul><li>SmartPass SPUUID</li><li>Verified and Unique EID  </li><li>If both Email and Mobile are verified (link with Verified Email & Mobile)    </li></ul> |
| <p>Account Linking (One time activity)</p><p>2 Records are Found</p><p>Auto matching the user information between UAE PASS and local account.</p>               | SOP 1, 2, 3  | If more than one email is found under 1 unique verified EID                                                                                                                                                                                         |


# Manual Linking

If user is having existing native credentials in service provider portal, but no matching attributes (Email or Emirates ID), service provider should provide an option for the user to manually link both the accounts.&#x20;

Service Providers delegate the authentication processes to UAEPASS. By doing so, Service Providers should be able to identify UAEPASS users and link them to their internal user repository through key attributes shared by UAEPASS. Every profile in UAEPASS has a unique identifier (UUID) that could be used as a key attribute to link users in Service Providers repository, and Emirates ID when dealing with Verified users (SOP2 and SOP3).

{% hint style="warning" %}
**Note:** At anytime, users on UAE PASS can update their email and mobile number after verifying that the user is in possession of the email address or mobile number.&#x20;

As such, if Service Providers depend on mobile number or email address from UAEPASS to link users, this link becomes orphaned once the user change the values on UAEPASS. SP will end up creating multiple accounts for the same user.
{% endhint %}

![Figure 7: Account Linking](/files/-Mk0dttj0yX0LZ8KopSz)

| Local Account                                                                                                                           | User Profile | Action                                                                                                                                                                                                                                                                                              |
| --------------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>Manual Linking (One time activity)</p><p>This is user initiated to link their existing account in Service Provider with UAEPASS </p> | SOP 1, 2, 3  | <p>If no unique key attribute (SPUUID, EID, Email, Mobile). Ask the user if local account exists in SP</p><ul><li>If yes, user enters local SP username/password and link accounts</li><li>If no, the SP creates new user profile by popylating UAEPass data in SP registration form.<br></li></ul> |

### Page Layout

![](/files/j0pqstuLxia2uQC86fJh)

**Yes**: When clicked, the user will be redirected to the local service provider login page for both UAEPASS and local profile will be linked and merged.&#x20;

**No**: When clicked, the user will be redirected to the usual registration page where he/she will provide essential information (SP can pull KYC data from UAEPASS instead of asking the user to typre them, like Name, DOB, etc.)&#x20;

#### If User clicks Yes:

The user Needs to enter the logon credentials in order to link the local account with UAE PASS account.&#x20;

![](/files/H9vrwy9U0I7vMpQepROQ)

#### If User clicks No:

The SP will show the local registration form and populate UAE PASS data such as (EID, Name, Email, Mobile) and it should not be editable. The rest of the fields can be manually entered by the user.&#x20;

![](/files/GfpEtwFDwyGt0jenDBVa)

{% hint style="warning" %}
Note: User should not be able to Edit UAE PASS data in the Registration Form nor in User Profile.&#x20;
{% endhint %}


# Corporate Account

### Granting Access to Service Provider (Web to App)

![](/files/kVQ1TPbNt3nzMa7c16a8)

### The following steps is for Sign-in or Log-in:

![](/files/88B6jqKBsrqCbLwNkkHo)

### Automatic linking of individual accounts with corporate Account

![](/files/QHUTT5gI3VnhHKP7hzup)

### Manual linking of individual accounts with corporate Account

![](/files/mVJV4hJLm5idzLbQjBr9)

### Account Linking (Visual Flow)

![ ](/files/k7piJFAOZHHMd6Rgeopj)

1. SP should not link local verified accounts with UAE PASS unverified accounts.
2. SP should not use unverified/duplicated attributes while linking local accounts with UAE Pass.
3. In the new account registration process through UAE Pass (during sign up or post sign in):
   * SP should not request user to create username/password for SP local account.
   * SP can create username/password in the backend but NOT share it with user.
   * SP can communicate the local account details via email or SMS only once the user clicks on Forget Password in SP login channel.
4. For business services:
   * where the SP maintains a mapping of its users with corporate accounts; the UAE Pass UUID is to be linked corresponding to the corporate profiles authorized for the user.
   * In case SP uses different login credentials for corporate with no corresponding authorized Emirates ID numbers, then manual linking is to be performed.
   * Service Provider based on its business requirement may allow one of more UAE PASS UUID to be linked with one or more business accounts.


# Digital Signature

### Here are the articles in this Section:

{% content-ref url="/pages/FmFusKC4q2tXGvtrR2Nd" %}
[Digital Signature (Single Document)](/feature-guides/signature-integration-guide/digital-signature-single-document)
{% endcontent-ref %}

{% content-ref url="/pages/cBUXB8InPv2rvr8J5fbW" %}
[Digital Signature (Multiple Document)](/feature-guides/signature-integration-guide/digital-signature-multiple-document)
{% endcontent-ref %}


# Digital Signature (Single Document)

The feature facilitates to integrate digital signing for single documents.


# Signing Guide

The purpose of this is to share the details and guidelines to perform the Digital Signing on PDF Document using the digital identity issued to individual and/or organizations using UAEPASS.

## Description

UAEPASS offers API and a process for performing the PDF document signing.&#x20;

On a high level this operation is requested by a document signature portal or application (mobile/web) by entity (or user itself) on behalf of a user who logs in to the portal or application after authenticating in UAEPASS and completes the signing process.

### Eligibility of Digital Signature Feature Based on User Account Types

* **SOP1: Basic Unverified Account**

User account is unverified, only email Id and mobile number are verified. User does not have access to digital signature and data/document sharing capability of UAE PASS.

* **SOP2: Verified Account from Smart Pass / Dubai ID**

User account is verified. User digital signature is advanced level, and user can use digital signing feature only if advanced level signing is allowed through the implementation.

* **SOP3: Verified Account**

User account is verified. User digital signature is qualified level and has access to digital signing feature.

## Pre-Requisites

* <mark style="color:green;">**Using UAE PASS Authentication before prompting users to Sign documents with UAE PASS is mandatory to verify if the same user logged in is signing the document.**</mark>

## &#x20;**Steps of Document Signing:**&#x20;

{% content-ref url="/pages/-Mk5YUO713RPLdQ7Bvqr" %}
[1. Token](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/1.-obtaining-the-token-for-accessing-the-signature-operations)
{% endcontent-ref %}

{% content-ref url="/pages/-Mk5eEv2riY6DcEFOJyj" %}
[2. Create Signer Process](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/2.-creating-the-document-signature-process)
{% endcontent-ref %}

{% content-ref url="/pages/-Mk5tQq8a\_E4O2P8i15e" %}
[3. Sign Document](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/3.-executing-the-document-signature-process)
{% endcontent-ref %}

{% content-ref url="/pages/-Mk61KGjF2ThHSCLDb-5" %}
[4. Obtaining Document](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/4.-obtaining-the-signed-document)
{% endcontent-ref %}

{% content-ref url="/pages/-Mk6ZKB97qApw\_DS0eTM" %}
[5. LTV Configuration](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/ltv-configuration)
{% endcontent-ref %}

{% content-ref url="/pages/-Mk62PZIqmXOd3P2mz1h" %}
[6. Deleting Document](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/5.-deleting-the-document-signature-process)
{% endcontent-ref %}

## Sample Successful Digital signature printed in the pdf document

<div align="left"><figure><img src="/files/f2WMC0fWpYsxSg1JIF9V" alt=""><figcaption></figcaption></figure></div>


# Endpoints

Below is the standard endpoints for Staging and Production Environment:

**Staging**

<table><thead><tr><th width="182.66955222867227">Endpoints</th><th>URL</th></tr></thead><tbody><tr><td>Get Signing AccessToken</td><td>https://stg-id.uaepass.ae/trustedx-authserver/oauth/main-as/token</td></tr><tr><td>Create Sign Process</td><td>https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes</td></tr><tr><td>Get Signature Status</td><td>https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/{Add signer ProcessId}/result</td></tr><tr><td>Fetch Signed Document</td><td>https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/{Add documentId}/content</td></tr><tr><td>Delete SignProcess</td><td>https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/{AddsignerProcessId}/</td></tr></tbody></table>

**Production**

| Endpoints               | URL                                                                                                  |
| ----------------------- | ---------------------------------------------------------------------------------------------------- |
| Get Signing AccessToken | <https://id.uaepass.ae/trustedx-authserver/oauth/main-as/token>                                      |
| Create Sign Process     | <https://id.uaepass.ae/trustedx-resources/esignsp/v2/signer\\_processes>                             |
| Get Signature Status    | <https://id.uaepass.ae/trustedx-resources/esignsp/v2/signer\\_processes/{AddsignerProcessId}/result> |
| Fetch Signed Document   | <https://id.uaepass.ae/trustedx-resources/esignsp/v2/documents/{AdddocumentId}/content>              |
| Delete SignProcess      | <https://id.uaepass.ae/trustedx-resources/esignsp/v2/signer\\_processes/{AddsignerProcessId}/>       |

**Production**

{% hint style="info" %}
Note: Following fields “Add signer ProcessId”, “Add documentId” which are also highlighted above needs to be fetched from the output of “Create Sign Process Endpoint”. Details of the same has been illustrated below as a part of [create ](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/2.-creating-the-document-signature-process)and [delete ](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/5.-deleting-the-document-signature-process)signature process.&#x20;
{% endhint %}


# Document Signing Steps

### Here are the articles in this section:

{% content-ref url="/pages/-Mk5YUO713RPLdQ7Bvqr" %}
[1. Token](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/1.-obtaining-the-token-for-accessing-the-signature-operations)
{% endcontent-ref %}

{% content-ref url="/pages/-Mk5eEv2riY6DcEFOJyj" %}
[2. Create Signer Process](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/2.-creating-the-document-signature-process)
{% endcontent-ref %}

{% content-ref url="/pages/-Mk5tQq8a\_E4O2P8i15e" %}
[3. Sign Document](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/3.-executing-the-document-signature-process)
{% endcontent-ref %}

{% content-ref url="/pages/-Mk61KGjF2ThHSCLDb-5" %}
[4. Obtaining Document](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/4.-obtaining-the-signed-document)
{% endcontent-ref %}

{% content-ref url="/pages/-Mk6ZKB97qApw\_DS0eTM" %}
[5. LTV Configuration](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/ltv-configuration)
{% endcontent-ref %}

{% content-ref url="/pages/-Mk62PZIqmXOd3P2mz1h" %}
[6. Deleting Document](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/5.-deleting-the-document-signature-process)
{% endcontent-ref %}


# 1. Token

Obtaining the Token for Accessing the Signature Operations

Firstly, the document signature application/portal calls the UAEPASS API to obtain the access token using client credentials issued to them.

## API Calling Method

<mark style="color:green;">`POST`</mark> [https://stg-id.uaepass.ae/trustedx-authserver/oauth/main-as/token ](<https://stg-id.uaepass.ae/trustedx-authserver/oauth/main-as/token >)

#### Headers

| Name          | Type   | Description                               |
| ------------- | ------ | ----------------------------------------- |
| Authorization | string | Basic ZG9jc2lnbjpkZW1vZGVtbw==            |
| Content-Type  | string | application/x-www-form-urlencoded         |
| grant\_type   | string | client\_credentials                       |
| scope         | string | urn:safelayer:eidas:sign:process:document |

{% tabs %}
{% tab title="200 Content-Type: application/json;charset=utf-8
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache" %}

```
{
    "access_token": "6fed0c30a51643f9b6ad7365cf90d7e.....72848cf0fb3aee9ad5ac1811212",
    "token_type": "Bearer",
    "expires_in": 600,
    "scope": "urn:safelayer:eidas:sign:process:document"
}
 
```

{% endtab %}
{% endtabs %}

{% hint style="info" %} <mark style="color:$info;">**Note: Token remains valid for 10 mins. If the same user signs the document within that time period, token endpoint is not required to be invoked again.**</mark>
{% endhint %}


# 2. Create Signer Process

Creating the Document Signature Process

After obtaining the access token in [previous step](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/1.-obtaining-the-token-for-accessing-the-signature-operations), the portal/application requests the creation of the PDF document signature process by sending the following message to UAEPASS using the signature services API.

## API call will create a signing process at UAEPASS end

<mark style="color:green;">`POST`</mark> <https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes>

#### Headers

| Name                                            | Type   | Description                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer \<token>                                                     |
| Cache-Control<mark style="color:red;">\*</mark> | string | no-cache                                                            |
| Postman-Token<mark style="color:red;">\*</mark> | string | 0cb4e517-8db9-473c-7b14-0ca2555bc199                                |
| Content-Type<mark style="color:red;">\*</mark>  | string | multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW |

{% tabs %}
{% tab title="201 If the request is successfully processed, UAE PASS creates the signature process for the document and responds to the document signature portal with the following HTTP message.
Location: <https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/sp_c4eed0a1f478f72454803695d53c4c52> Content-Type: application/json" %}

```
{ 
    "id" : "sp_c4eed0a1f478f72454803695d53c4c52", 
    "self" : "Location: https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/sp_c4eed0a1f478f72454803695d53c4c52", 
    "process_type" : "urn:safelayer:eidas:processes:document:sign:esigp", 
    "tasks" : { 
        "pending" : [ 
            { 
                "type" : "UserBrowserTask", 
                "id" : "tk_fde244b585cd2feb54c3039b1498e4a4",
                "url" : "https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/ui?signerProcessId=sp_c4eed0a1f478f72454803695d53c4c5"
            }
        ]
    }, 
    "documents" : [ 
        { 
            "url" : "https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/dc_9ee0990055818516249f28558e1b256b" 
            } 
        ] 
    }
```

{% endtab %}
{% endtabs %}

```json
------WebKitFormBoundary7MA4YWxkTrZu0gW 
Content-Disposition: form-data; name="process"
{
  "process_type": "urn:safelayer:eidas:processes:document:sign:esigp",
  "labels": [
    [
      "digitalid",
      "server",
      "qualified"
    ]
  ],
  "signer": {
    "signature_policy_id": "urn:safelayer:eidas:policies:sign:document:pdf",
    "parameters": {
      "type": "pades-baseline",
      "signature_field": {
        "name": "Sign1",
        "location": {
          "page": {
            "number": "last"
          },
          "rectangle": {
            "x": 100,
            "y": 110,
            "height": 150,
            "width": 400
          }
        },
        "appearance": {
          "signature_details": {
            "details": [
              {
                "type": "subject",
                "title": "Signer Name: "
              },
              {
                "type": "date",
                "title": "Signature Date: "
              }
            ]
          }
        }
      }
    }
  },
  "ui_locales": [
    "en_US"
  ],
  "finish_callback_url": "http://localhost:8080/test",
  "views": {
    "document_agreement": {
      "skip_server_id": "true"
    }
  },
  "timestamp": {
    "provider_id": "urn:uae:tws:generation:policy:digitalid"
  }
}
                        
------WebKitFormBoundary7MA4YWxkTrZu0gW 
Content-Disposition: form-data; name="document"; filename="{pdf to be signed}"
Content-Type: application/pdf 
------WebKitFormBoundary7MA4YWxkTrZu0gW--                   
```

List of Attributes for POST Body.

<table data-header-hidden><thead><tr><th>Functionality</th><th width="156">Attributes</th><th width="150">Required</th><th>How to use it ?</th></tr></thead><tbody><tr><td>Multiple signatures in a document</td><td>signature_field</td><td>Mandatory</td><td>If there is an use case to put multiple signature by multiple user , then Value of the “name” has to be changed in the above request body. In the above example, it’s now as follows for first user who sign the document. For 2nd user , it should be with different name. such as “Sign2” or any. </td></tr><tr><td>View the document before signing</td><td>skip_server_id</td><td>Mandatory</td><td>If there is an use case of viewing or downloading the PDF document, then Change the value of attributes “skip_server_id” to “false” in stead of “true” what it is mentioned in the above example.</td></tr><tr><td>Getting signature appeared on Emirate ID and put it in Digital Signature.</td><td>background_image</td><td>Optional</td><td><p>To get the signature from emirate Id card and put it in the Digital Signature. Attributes “background_image” to be used as follows under appearance attributes. </p><p>Value of Attribute “cardHolderSignatureImage” from user profile information to be used as value of “background_image” for the signature. "appearance": { </p><p>         "background_image": { </p><p>             "binary": "&#x3C;&#x3C;base64 image>>" </p><p> },</p></td></tr><tr><td>Putting fore ground image in digital Signature</td><td>foreground_image</td><td>Optional</td><td><p>"appearance": { </p><p>           "foreground_image": {  </p><p>           "binary": "{base64 image}" </p><p>},</p></td></tr><tr><td>Digital Signature with both foreground and back ground image</td><td>background_image foreground_image</td><td>Optional</td><td><p>"appearance" : {</p><p>"background_image" : {</p><p>"binary" : {base64}</p><p>},</p><p>"foreground_image" : { </p><p>"binary" : {base64}</p><p>},</p></td></tr><tr><td>Which page to put the Signature</td><td>Page</td><td>Mandatory</td><td>By default, Signature can be put in last page as mentioned in above request body <br>"page" : { <br>"number" : "last" <br>… <br>},</td></tr><tr><td>To display the signature image or to hide the signature image on the document</td><td>appearance</td><td>Optional</td><td><p>If SP needs to display the signature image on the document, they can use the below.</p><p> </p><p>"appearance": {</p><p>"signature_details": {</p><p>"details": [{</p><p>"type": "subject",</p><p>"title": "Signer Name: "</p><p>},</p><p>{</p><p>"type": "date",</p><p>"title": "Signature Date: "</p><p>}]</p><p>}</p><p>If SP needs to hide the signature image, they can use the below as passing the appearance parameter as blank:</p><p> </p><p>"appearance": {</p><p> </p><p>}  </p><p>If SP needs to hide the EID from the signature image, they can use the following. </p><p></p><p>"appearance": </p><p>{ "signature_details":</p><p> { "details":</p><p> [ {</p><p> "type": "date", </p><p>"title": "Signature Date: "</p><p> }]</p><p> }</p><p> }</p></td></tr></tbody></table>

UAEPASS communicates with the signature portal, that successfully creates the signature process and that must redirects the user's browser to [https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/ui?signerProcessId=sp\_c4eed0a1f478f72454803695d53c4c5](https://qa-id.uaepass.ae/trustedx-resources/esignsp/v2/ui?signerProcessId=sp_c4eed0a1f478f72454803695d53c4c5) (tasks.pending.url) for this process to continue.&#x20;

It also communicates to the signature portal that obtain the signed document it must access [https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/dc\_9ee0990055818516249f28558e1b256b/content](https://qa-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/dc_9ee0990055818516249f28558e1b256b/content) (i.e., the URL resulting from concatenating /content to the URL specified in documents\[0].

{% hint style="warning" %}
If signing the same document twice, make sure that unique value is passed for the name parameter in process type of request body as below:

"name": "Sign1" for the first signature

"name": "Sign2" for the second signature

"cardHolderSignatureImage"- Retrieval of this attribute from UAE PASS is subject to approvals from ICP team.
{% endhint %}


# 3. Sign Document

Executing the Document Signature Process

The portal orders that the signature process be executed via the browser.&#x20;

The URL to which the browser is redirected must be extracted from the JSON response from the previous operation i.e. creation of document signature process. Specifically, the redirect URL is extracted from the URL field of the only element currently contained in the tasks.pending array of a recently created signature process (an element whose type is always UserBrowserTask). The execution of the signature process of a document is finished by sending a redirect response to the application/portal browser with which the user requested the signature.

<mark style="color:blue;">`GET`</mark> <https://stg-id.uaepass.ae/trustedx-resources/esigp/v1/signatures/{signature_id}/result>

#### Path Parameters

| Name          | Type   | Description                                                         |
| ------------- | ------ | ------------------------------------------------------------------- |
| signature\_id | string | Identifier of the signature creation process whose result you want. |

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | Bearer \<token> |

{% tabs %}
{% tab title="302 If the operation is performed successfully, the body contains a JSON object with the following structure
{
"status": {string},
"details": {
"message": {string}
}
}

status (required):
Result of the document signature process:

* "finished": The process finished after all the documents were correctly signed.
* "failed": The process finished but no document was signed owing to an error.
* "failed\_documents": The process finished. Some of the documents were signed, but not all.
* "canceled": The process finished but no document was signed because the process was canceled.

details.message (Optional):
Additional information on the result of the document signature process.

Status of the finalized signature creation process (finished, failed or canceled):

* finished: The process has finalized after having successfully created the signature.
* failed: The process has terminated without being able to create the signature because an error occurred.
* canceled: The process terminated without a signature having been created because it was canceled.
* "failed\_documents": The process finished. Some of the documents were signed, but not all. " %}

```
Location: https://localhost:8080/callback?status=finished&signer_process_id=sp_c4eed0a1f478f72454803695d53c4c52
```

{% endtab %}
{% endtabs %}

> Example:\
> GET /trustedx-resources/esigp/v1/signatures/123-1234567/result HTTP/1.1 \
> Authorization: Bearer mF\_9.B5f-4.1JqM

### Response&#x20;

If the operation is performed successfully, the body contains a JSON object with the following structure

```
{
"status": {string}, "details": { "message": {string}}
}
```

| Property        | Usage    |                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status          | Required | <p>Result of the document signature process:</p><p> </p><ul><li>"finished": The process finished after all the documents were correctly signed.</li><li>"failed": The process finished but no document was signed owing to an error.</li><li>"failed\_documents": The process finished. Some of the documents were signed, but not all.</li><li>"canceled": The process finished but no document was signed because the process was canceled.</li></ul> |
| details.message | Optional | Additional information on the result of the document signature process.                                                                                                                                                                                                                                                                                                                                                                                 |


# 4. Obtaining Document

Obtaining the Signed Document

Following the [previous step](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/3.-executing-the-document-signature-process), the signature portal sends the following message to UAEPASS to obtain the signed PDF document.

## Obtain Signed PDF Document

<mark style="color:blue;">`GET`</mark> <https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/{document_id}/content>

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | Bearer \<token> |

{% tabs %}
{% tab title="200 Note that for the sake of readability, {pdfSigned} replaces the binary content of the signed PDF." %}

```
Content-Type: application/pdf 

{pdfSigned}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Note that the portal demonstrates its authorization for obtaining the signed document by including the access token (403e...e7b3) in the Authorization header.&#x20;

Also note that the URL of the document requested is created by adding /content to the URL specified in the response received when the signature process for the document was created (the document\[0].url property of the JSON object contained in the response)
{% endhint %}


# 5. LTV Configuration

The purpose of this is to share the details and guidelines to perform the LTV -Long Term validations on PDF Document using the LTV configuration API issued to entity/organizations with UAEPASS.

### Description

UAEPASS offers API and a process for performing the LTV signature on documents on a high level, this operation is requested by a LTV portal or application (mobile/web) by an authorized user of the entity on behalf of that entity. \
LTV Long Term validation the document entails single synchronous SOAP based web service call.&#x20;

When LTV is enabled, the certificates sign-time status is captured and stored inside the PDF document. This is indicated within the signature details if it is LTV enabled or not. This verification certificate remains in the file itself so that its validity can be determined even at some later date, regardless of whether the certificate has expired, been revoked, or the issuing authority no longer exists. Because the record is stored inside the signed document, it is also authenticated by the document’s signature, further reducing chances for error or fraud.&#x20;

LTV helps reduce dependencies on external systems and reduces the potential for future ambiguity around expired or revoked certificates.&#x20;

LTV signature validations are done by PAdES (PDF Advanced Electronic Signatures) is a set of restrictions and extensions to PDF and ISO 32000-1 making it suitable for Advanced Electronic Signature. PAdES recognizes that digitally-signed documents may be used or archived for many years – even many decades. At any time in the future, in spite of technological and other advances, it must be possible to validate the document to confirm that the signature was valid at the time it was signed.&#x20;

When the user signs a document, the digital signature application also requests and embeds within their signature a secure timestamp from a trusted Time Stamp Authority (TSA). The timestamp returned by the TSA is digitally signed by the TSA so that it can be independently authenticated and trusted; it is also linked to the original signed document so it cannot be used with some other document. The embedded timestamp provides independent proof of the time of signing.&#x20;

UAEPASS digital signature application also contacts the appropriate Validation Authority (VA) to retrieve the certificate status for the signer’s certificate. The certificate status OCSP response is provided by the VA and provides an authoritative view on whether the certificate is currently trusted. UAEPASS digital signature application also embeds this certificate status information inside the signature for future verification by anyone.

{% hint style="info" %}
LTV implementation is mandatory after digital signature&#x20;
{% endhint %}


# Integration Web Services

### SOAP Gateway Endpoint

| Staging                                                                                               | Production                                      |
| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [https://stg-id.uaepass.ae/trustedx-gw/SoapGateway](https://qa-id.uaepass.ae/trustedx-gw/SoapGateway) | <https://id.uaepass.ae/trustedx-gw/SoapGateway> |

## Transport Headers to invoke SOAP Service

<mark style="color:green;">`POST`</mark> `https://stg-id.uaepass.ae/trusted-gw/SoapGateway`&#x20;

#### Headers

| Name         | Type   | Description                                             |
| ------------ | ------ | ------------------------------------------------------- |
| TwsAuthN     | string | urn:safelayer:tws:policies:authentication:oauth:clients |
| SOAPAction   | string | Update                                                  |
| Content-Type | string | text/xml                                                |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

### Request

```markup
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- wssecurity-secext-1.0.xsd" soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="1">
<wsse:UsernameToken>
<wsse:Username>XXXX</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- username-token-profile-1.0#PasswordText">XXXXX</wsse:Password><!-- 9QWtRunFT3-->
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<VerifyRequest Profile="urn:safelayer:tws:dss:1.0:profiles:nonrep:1.0" RequestID="b22c97c6117fc3386f81" xmlns="http://www.docs.oasis- open.org/dss/2004/06/oasis-dss-1.0-core-schema-wd-27.xsd">
<OptionalInputs>
<ReturnUpdatedSignature Type="urn:oasis:names:tc:dss:1.0:profiles:XAdES: forms:ES-A"/>
<css:PdfFieldLabel>SFLY Signature 0</css:PdfFieldLabel>
</OptionalInputs>
<InputDocuments>
<Document>
<Base64Data MimeType="application/pdf">XXX</Base64Data
</Document>
</InputDocuments>
</VerifyRequest>
</soapenv:Body>
</soapenv:Envelope>
```

### Request Parameters

|              |                                                                                    |           |
| ------------ | ---------------------------------------------------------------------------------- | --------- |
| Username     | client\_id of the SP. To be shared by the respective onboarding team.              | Mandatory |
| PasswordText | Client\_secret of the SP. To be shared by the respective onboarding team.          | Mandatory |
| RequestID    | SP can pass the unique ID for tracking the request for one particular transaction. | Optional  |
| Base64Data   | Base64 encoded data of the document which is to be LTV signed.                     | Mandatory |

### Sample Request/Response (with sample data):

The integration team can try below request in any SOAP service testing tool (e.g. SOAPUI, PostMan etc.) by replacing the username password as provided by UAEPASS onboarding team.

<mark style="color:green;">`POST`</mark> `stg-id.uaepass.ae/trusted-gw/SoapGateway`&#x20;

HTTP/1.1

#### Headers

| Name         | Type   | Description                                                             |
| ------------ | ------ | ----------------------------------------------------------------------- |
| TwsAuthN     | string | <p>urn:safelayer:tws:policies:authentication:oauth:<br> clientsSOAP</p> |
| Action       | string | Verify                                                                  |
| Content-Type | string | text/xml                                                                |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

#### Request Sample

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance">
<soapenv:Header>
<wsse:Security soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- wssecurity-secext-1.0.xsd">
<wsse:UsernameToken>
<wsse:Username>XXXXX</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username- token-profile-1.0#PasswordText">XXXXX</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
  <VerifyRequest Profile="urn:safelayer:tws:dss:1.0:profiles:pdf:1.0:verify" RequestID="ba3810598a90af56a7e8" xmlns="http://www.docs.oasis-open.org/dss/2004/06/oasis-dss-1.0- core-schema-wd-27.xsd">
    <OptionalInputs>
      <ns1:AddCertificateValues binary="true" xsi:type="ns1:AddCertificateValuesType" xmlns:ns1="http://www.safelayer.com/TWS"/>
      <ns2:AddSignatureForm/>
      <css:AddRevocationValues binary="true"/>
      <css:AddTimeStampValues binary="true"/>
    </OptionalInputs>
    <InputDocuments>
      <Document>
        <Base64Data MimeType="application/pdf">JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUG FnZXMgMiAwIFIvTGFuZyhlbi1VUykgL1N0cnVjdFRyZWVSb290IDkgMCBSL01hcmtJbmZvPDwvTWFya2V kIHRydWU+Pj4+DQplbmRvYmoNCjIgMCBvYmoNCjw8L1R5cGUvUGFnZXMvQ291bnQgMS9LaWRzWyA zIDAgUl0gPj4NCmVuZG9iag0KMyAwIG9iag0KPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJj ZXM8PC9YT2JqZWN0PDwvSW1hZ2U1IDUgMCBSPj4vRXh0R1N0YXRlPDwvR1M3IDcgMCBSPj4vUHJv
        Y1NldFsvUERGL1RleHQvSW1hZ2VCL0ltYWdlQy9JbWFnZUldID4+L01lZGlhQm94WyAwIDAgNjEyIDc5Ml 0gL0NvbnRlbnRzIDQgMCBSL0dyb3VwPDwvVHlwZS9Hcm91cC9TL1RyYW5zcGFyZW5jeS9DUy9EZXZp Y2VSR0I+Pi9UYWJzL1MvU3RydWN0UGFyZW50cyAwPj4NCmVuZG9iag0KNCAwIG9iag0KPDwvRmlsd GVyL0ZsYXRlRGVjb2RlL0xlbmd0aCAxMTM+Pg0Kc3RyZWFtDQp4nBWKsQqDMBRF9wfvH+7skLwXrDEgDk2KOAgVB2cRcdJS+//QeIcznHNh32gaO8Q+QdoWzxRhu8lj/zF9mcTIvaAOgirTB4drY5oLnEwqajQXgda
        mQsh3V8JnW2I9mGx/LPv2QPpgZMJriPgDPogXfg0KZW5kc3RyZWFtDQplbmRvYmoNCjUgMCBvYmoNC jw8L1R5cGUvWE9iamVjdC9TdWJ0eXBlL0ltYWdlL1dpZHRoIDIvSGVpZ2h0IDIvQ29sb3JTcGFjZVsvSW5k ZXhlZC9EZXZpY2VSR0IgMSA8MDAwMDAwRkZGRkZGPl0gL0JpdHNQZXJDb21wb25lbnQgMS9JbnRlcn BvbGF0ZSBmYWxzZS9TTWFzayA2IDAgUi9MZW5ndGggMj4+DQpzdHJlYW0NCgAADQplbmRzdHJlYW0 NCmVuZG9iag0KNiAwIG9iag0KPDwvVHlwZS9YT2JqZWN0L1N1YnR5cGUvSW1hZ2UvV2lkdGggODQyL 0hlaWdodCAxNTQvQ29sb3JTcGFjZS9EZXZpY2VHcmF5L0JpdHNQZXJDb21wb25lbnQgMS9GaWx0ZXIv RmxhdGVEZWNvZGUvTGVuZ3RoIDExOTU+Pg0Kc3RyZWFtDQp4nO3ZS47cNhAAUNI0wCVzgjAHMaAc K6tQgQ/io0RH0S5bZccFIbo+LKql1sz0jDWDfKph9Mglqp6+JEttzAd9ho+CVFJJJZVUUkkllVRSSSWVVFJJ pX+JZOdXb+qmN0nx9dKg0jBU/CwshVHi7mX5h6TYN/bL+0rDLPGQ31dKi8RjUekfJUFHtBp5nj5Oetd7bye 96/O0k077iC24X/GolM+k00/aSVvDByWvkkr/Q8kXnlhVTrz0vokkWsYvkUJBaVioxUSzuC/GjbA6YIx6M8p5L 1UgYONQaQ00d3WlNBX+WlzGQKyVdwX+Tq2JrwV3wBWTvtZCTWGrkXN6aDjvpL9wS5BgFGlSwAhJBZ LBlhhACdc7kiKx8C3St1oDxiymp5y+cppNIhqkxCtAgtAiUmx5F5E4wUD7i5s0CaJ/ouRxW8p5Ki0oVc4P0oB EkyglBkSKlIAb4wndJFoBB5Y556mUQbLttIKUKl0ykhKmxIBIOFRT44xn6iDNmK5wzhNpGlBydUzt7NU59r MHy5kCIiW48tB4GorBTeQ6VTjAMcHhZ79yznup4I0J0mqCSKNb2l1u4R4qHGh3OV1UV+FmN5AziAQHXv BhSLOFu2TFnHd3+WIg1zDBlxtJgqZmbhL4rnBApLE1XhH7JNKET1jEvTS15TzpI1iCeJMg/ItIBVpxgCVUhy ngReKHtEkjHhBKuBnnPJGcSKZLpkleJOkjcBmkBSW6ml2iTsKK5F4tQXQnOZFM5chBwtVvlupOKijhMu36 qTS9IJUu1U2inecAS/5Goj59L/UdeUZyVSTDj8EmcaBJ+QJp6tJylJaDhMYPSKVLtUvYM1QOHCX4Hu8kT7 3f85Jtww/1e/NeokCb7C6blN4mGe7KuS8ve4kC10mJ8/P4tJcocJ0U+5jrWyfcJQpcJ3m+UNTR8IXqEg/Zl0m mj+5wXRaR+N7AwGMSZX9JijLmwuHlvYSBCyUr8wgcWPcSBi6UuKwmKR6leK0Uu+SPkt9LuDyMb5doD CXJrU2i/3GgSTc9LM1w7vu9ByTfJXuUrEgP9OXXSsv1Uj6VeDAZ5ntpfVn6tEnjJvGtMd5Ipc2NzqU+PD83P o1dmkWaKPFPHKA7U2YsuUUsfh2kzyKVc8lPrdJaLG1rqPbDxL9xgC8ZTgJSm1nCPNqjFDYJZ5Y/t5zuKS nL8wRh3p1h/gxTb5s5ELLFCwaB2mbL8C+OONW+lWbzu0ir+fVMCjC0ziTBjCLSKR6WL7bOoXAglEDSHK QCgE3qGFZbb6SUnVRvrvKPBUcp9qrGV65qoMstWCIVDngev+pW1VA1gV830lB7nWiPtUY/Jhk1XKvZQF qp2OVAG7/SVqk5Kf1upLjVVDLM3c+N+kjYjg7Ozor7mDngeD1ValyqUqXm9lLAMpxzmickU7li5zMw0rPDJf vMgTZ5gkCcWkWdqLivf99IvvJQhlJ6Qor9LYFnE5JkPBLTAmllPkecChRSM+b740YybcqBUuQdvvuly8okeX v/i501veKgAD+67QUJNba4fHhxG7Y3xu3R/S//eqeSSiqppJJKKqmkkkoqqaSSSiqppJJKKl0mfQfGpmwvDQ plbmRzdHJlYW0NCmVuZG9iag0KNyAwIG9iag0KPDwvVHlwZS9FeHRHU3RhdGUvQk0vTm9ybWFsL2Nh IDE+Pg0KZW5kb2JqDQo4IDAgb2JqDQo8PC9BdXRob3IoTW9oYW1tYWQgWXVzdWYgS2hhbikgL0NyZ WF0b3Io/v8ATQBpAGMAcgBvAHMAbwBmAHQArgAgAFcAbwByAGQAIAAyADAAMQA2KSAvQ3JlYXRp b25EYXRlKEQ6MjAxODEwMTMwMzE3NDArMDQnMDAnKSAvTW9kRGF0ZShEOjIwMTgxMDEzMDMxN zQwKzA0JzAwJykgL1Byb2R1Y2VyKP7/AE0AaQBjAHIAbwBzAG8AZgB0AK4AIABXAG8AcgBkACAAMgA
        wADEANikgPj4NCmVuZG9iag0KMTYgMCBvYmoNCjw8L1R5cGUvT2JqU3RtL04gOC9GaXJzdCA1Mi9Ga Wx0ZXIvRmxhdGVEZWNvZGUvTGVuZ3RoIDM0Mz4+DQpzdHJlYW0NCniclZJda8IwFIbvB/6Hc7ldpamrsy CCTGVDFGkLuxAvYnvWFttE0hT03y+nH7MwbwYlPV/vk5yT8FdwgL/B1Ac+Bu5NgLvgch98cCdT4A6MPZ vi4PmeTcOET2E2Y3uqdiBgIQsvQrLodkEWGl3HZlVgyRaxqUUR4dU8R1legf0MVgYSFdclSvMCbHMA5wh sn0JDms9HT/8DQwN5iHA7xP6P3u7KqeWAmra/R3K/VwttHgLGrbITDCoijRgoZVigCtyKC82PWJZkm6Ysj ZIihHH7A/xmd7avDd6Ad+i1ZUllkO1oWcnk7tAITurKQowN+0CRoG5t0vT2pyxyiWEm6IQUWEhLECZXsvO 1yb+FNRrvS+nzSakzW3bX1ESqDNG0w9iKWKuB/57ZdeAvc1GodBAIizzBQW27jy1LtSjZOk9rjV2vu7qsDv QYvft0+8s6wujpBwpmzsUNCmVuZHN0cmVhbQ0KZW5kb2JqDQoxOCAwIG9iag0KPDwvVHlwZS9YUmV mL1NpemUgMTgvV1sgMSA0IDJdIC9Sb290IDEgMCBSL0luZm8gOCAwIFIvSURbPDdDQTMxNTQxMDkw OTQ0NDY4QjQ3NjA5ODc1RTJBRjU2Pjw3Q0EzMTU0MTA5MDk0NDQ2OEI0NzYwOTg3NUUyQUY1Nj5d
        IC9GaWx0ZwMDA1NDAyNSAwMDAwMCBuIAowMDAwMDU0MDk5IDAwMDAwIG4gCjAwMDAwNTQyNzcgM DAwMDAgbiAKMDAwMDA3OTIxNSAwMDAwMCBuIAowMDAwMDU0MTQ2IDAwMDAwIG4gCjAwMDAw
        NzkwMzkgMDAwMDAgbiAKMDAwMDA3OTEzOCAwMDAwMCBuIAp0cmFpbGVyCjw8L1NpemUgNDkvU m9vdCAxIDAgUi9JbmZvIDggMCBSL0lEIFs8N2NhMzE1NDEwOTA5NDQ0NjhiNDc2MDk4NzVlMmFmNTY
        +PGEwN2RjZTMxM2RmMjc4YmJhZmE4NDEzODUzOWU5NTcwPl0vUHJldiAzMzc3NT4+CiVpVGV4dC0 1LjUuMTIKc3RhcnR4cmVmCjgwMjQwCiUlRU9GCg==
        </Base64Data>
      </Document>
    </InputDocuments>
  </VerifyRequest>
</soapenv:Body>
</soapenv:Envelope>


```

#### Response Sample

```markup
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<dss:SignResponse xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xmln
s:css="http://www.safelayer.com/TWS" xmlns:dss="http://www.docs.oasis-open.org
/dss/2004/06/oasis-dss-1.0-core-schema-wd-27.xsd" xmlns:xades="http://uri.etsi
.org/01903/v1.2.2#" Profile="urn:safelayer:tws:dss:1.0:profiles:pades:1.0:sign "
RequestID="b22c97c6117fc3386f81" >
<dss:Result>
<dss:ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Succes
s</dss:ResultMajor>
</dss:Result>
<dss:OptionalOutputs>
<dss:DocumentWithSignature>
<dss:XMLData>
<dss:Base64Data MimeType="application/pdf">JVBERi0xLjU
NCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFuZyhlbi1VUykgL 
1N0cnVjdFRyZWVSb290IDkgMCBSL01hcmtJbmZvPDwvTWFya2VkIHRydWU+Pj4+DQplbmRvYmoNCjI 
gMCBvYmoNCjw8L1R5cGUvUGFnZXMvQ291bnQgMS9LaWRzWyAzIDAgUl0gPj4NCmVuZG9iag0KMyAwI 
G9iag0KPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9YT2JqZWN0PDwvSW1hZ2U 
1IDUgMCBSPj4vRXh0R1N0YXRlPDwvR1M3IDcgMCBSPj4vUHJvY1NldFsvUERGL1RleHQvSW1hZ2VCL
0ltYWdlQy9JbWFnZUldID4+L01lZGlhQm94WyAwIDAgNjEyIDc5Ml0gL0NvbnRlbnRzIDQgMCBSL0d 
yb3VwPDwvVHlwZS9Hcm91cC9TL1RyYW5zcGFyZW5jeS9DUy9EZXZpY2VSR0I+Pi9UYWJzL1MvU3Ryd
JUVPRgo=</dss:Base64Data>
                    </dss:XMLData>
                </dss:DocumentWithSignature>
                <css:NumberPdfSignatures>2</css:NumberPdfSignatures>
            </dss:OptionalOutputs>
        </dss:VerifyResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


```

### Error Codes

| Code                                                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| urn:oasis:names:tc:dss:1.0: resultminor:NotAuthorized                       | The requester or the requested party is not authorized to perform this operation.                                                                                                                                                                                                                                                                                                                                                                         |
| urn:oasis:names:tc:dss:1.0: resultminor:NotSupported                        | The server does not recognize or support some aspect of the request.                                                                                                                                                                                                                                                                                                                                                                                      |
| urn:safelayer:dss:1.0: resultminor:PolicyViolation                          | The server cannot process the request owing to a service policy violation.                                                                                                                                                                                                                                                                                                                                                                                |
| urn:safelayer:dss:1.0:resultminor:SignerCertificateNotFound                 | Signer's certificate not found in the signature or in the verification request.                                                                                                                                                                                                                                                                                                                                                                           |
| urn:oasis:names:tc: dss:1.0:resultminor:NotSupported                        | The server cannot process the content of a valid element in the request owing to an unexpected error. The dss:ResultMessage element can include lower level information on the reasons for the error.                                                                                                                                                                                                                                                     |
| urn:safelayer:dss:1.0: resultminor:SigningError                             | The input data and parameters are correct, but the server cannot generate the signature requested owing to an unexpected error. The dss:ResultMessage element can include lower level information on the reasons for the error.                                                                                                                                                                                                                           |
| urn:oasis:names:tc:dss:1.0:resultminor: ValidSignature\_OnAllDocuments      | The signature or timestamp is valid and includes all the input documents indicated in the request.                                                                                                                                                                                                                                                                                                                                                        |
| urn:oasis:names:tc:dss:1.0:resultminor: ValidSignature\_NotAllDocuments     | There are multiple signatures or timestamps but not all are valid.                                                                                                                                                                                                                                                                                                                                                                                        |
| urn:oasis:names:tc:dss:1.0:resultminor: IncorrectSignature                  | <p>The signature cannot be verified (the</p><p> that comes with this result indicates the causes of the error)</p>                                                                                                                                                                                                                                                                                                                                        |
| urn:safelayer:dss:1.0: resultminor: IncorrectKeySelected                    | Signature not generated owing to the selection of an invalid key.                                                                                                                                                                                                                                                                                                                                                                                         |
| urn:safelayer:dss:1.0: resultminor: IncorrectAlgorithmIdentifier            | The selected signature algorithm is not supported.                                                                                                                                                                                                                                                                                                                                                                                                        |
| urn:safelayer:dss:1.0: resultminor: IncorrectFormatInData                   | Incorrect input data.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| urn:safelayer:tws:dss:1.0: profiles:resultminor: UntrustedKey:CA            | The signed message has not been modified but the signature key is not trusted (because the certification chain could not be built or because the CA certificate is not trusted).                                                                                                                                                                                                                                                                          |
| urn:safelayer:tws:dss:1.0: profiles:resultminor: UntrustedKey:Validity      | The signed message has not been modified and the certification chain is trusted. However, the signature key is not trusted because the certificate has expired and it cannot be verified that the signature was generated when the certificate was valid.                                                                                                                                                                                                 |
| urn:safelayer:tws:dss:1.0: profiles:resultminor: UntrustedKey:Status        | <p>The signed message has not been edited, the certification chain is trusted and the signature was generated with a valid certificate. However, the server could not verify that the signature key was valid. Either because the status information indicates that the signature was invalid or because the status information could not be queried. The</p><p> element of the XML message contains further information on the certificate's status.</p> |
| urn:safelayer:tws:dss:1.0: profiles:resultminor: IncorrectArchiveSignature  | <p>The archive signature cannot be verified (the</p><p> element indicates the causes of the error).</p>                                                                                                                                                                                                                                                                                                                                                   |
| urn:safelayer:tws:dss:1.0:profiles:resultminor:UntrustedKey:GoodWit hNoInfo | The signed message has not been edited, and the signature key is trusted. However, the status of all the certificates in the certification chain cannot be determined owing to a lack of revocation information in the long-term signature.                                                                                                                                                                                                               |


# Postman Collection for LTV

{% file src="/files/-Mkp4-3UeQzSfs8-6hN2" %}
LTV Postman Collection
{% endfile %}


# 6. Deleting Document

Deleting the Document Signature Process

After obtaining the [signed PDF document](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/4.-obtaining-the-signed-document), the document signature portal sends the following message to UAEPASS to delete the document signature process used.&#x20;

## Delete Document Signature

<mark style="color:red;">`DELETE`</mark> <https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/{process_id}>

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | Bearer \<token> |

{% tabs %}
{% tab title="204 UAEPASS deletes the document signature process and responds with the following message" %}

```
No content
```

{% endtab %}
{% endtabs %}


# Document Signature verification Process

UAE PASS document signature verification API offers for the signer’s identity verification through UAE PASS digital signature feature. On integrating the UAE PASS Document signature verification feature SP can validate the document singed time, signer details up to 3 years.

### SOAP Gateway Endpoint

| Staging                                                                                               | Production                                      |
| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [https://stg-id.uaepass.ae/trustedx-gw/SoapGateway](https://qa-id.uaepass.ae/trustedx-gw/SoapGateway) | <https://id.uaepass.ae/trustedx-gw/SoapGateway> |

## Transport Headers to invoke SOAP Service

<mark style="color:green;">`POST`</mark> `https://stg-id.uaepass.ae/trusted-gw/SoapGateway`&#x20;

#### Headers

| Name         | Type   | Description                                             |
| ------------ | ------ | ------------------------------------------------------- |
| TwsAuthN     | string | urn:safelayer:tws:policies:authentication:oauth:clients |
| SOAPAction   | string | Verify                                                  |
| Content-Type | string | text/xml                                                |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

### Request

```xml
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Header>
      <wsse:Security soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken>
            <wsse:Username>{client_id}</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">{client_secret}</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <VerifyRequest Profile="urn:safelayer:tws:dss:1.0:profiles:pdf:1.0:verify" RequestID="ba3810598a90af56a7e8" xmlns="http://www.docs.oasis-open.org/dss/2004/06/oasis-dss-1.0-core-schema-wd-27.xsd">
         <OptionalInputs>
            <ns1:AddCertificateValues binary="true" xsi:type="ns1:AddCertificateValuesType" xmlns:ns1="http://www.safelayer.com/TWS"/>
            <ns2:AddSignatureForm/>
            <css:AddRevocationValues binary="true"/>
            <css:AddTimeStampValues binary="true"/>
         </OptionalInputs>
         <InputDocuments>
            <Document>
            <Base64Data MimeType="application/pdf">JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9DcmVhdGlvbkRhdGUoRDoyMDIxMDgwNjEwMjcwMSkvQ3JlYXRvcihQREZpdW0pL1Byb2R1Y2VyKFBERml1bTsgbW9kaWZpZWQgdXNpbmcgaVRleHRTaGFycJIgNS41LjEzLjEgqTIwMDAtMjAxOSBpVGV4dCBHcm91cCBOViBcKEFHUEwtdmVyc2lvblwpKS9Nb2REYXRlKEQ6MjAyMTA5MjMwNjI2MTYrMDAnMDAnKT4</Base64Data>
          </Document>
         </InputDocuments>
      </VerifyRequest>
   </soapenv:Body>
</soapenv:Envelope>

```

### Request Parameter

| Name         | Description                                                                        | Required  |
| ------------ | ---------------------------------------------------------------------------------- | --------- |
| Username     | client\_id of the SP. To be shared by the respective onboarding team.              | Mandatory |
| PasswordText | Client\_secret of the SP. To be shared by the respective onboarding team.          | Mandatory |
| RequestID    | SP can pass the unique ID for tracking the request for one particular transaction. | Optional  |
| Base64Data   | Base64 encoded data of the document which is to be verified                        | Mandatory |

### Sample Request

```svg
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Header>
      <wsse:Security soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken>
            <wsse:Username>{client_id}</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">{client_secret}</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <VerifyRequest Profile="urn:safelayer:tws:dss:1.0:profiles:pdf:1.0:verify" RequestID="ba3810598a90af56a7e8" xmlns="http://www.docs.oasis-open.org/dss/2004/06/oasis-dss-1.0-core-schema-wd-27.xsd">
         <OptionalInputs>
            <ns1:AddCertificateValues binary="true" xsi:type="ns1:AddCertificateValuesType" xmlns:ns1="http://www.safelayer.com/TWS"/>
            <ns2:AddSignatureForm/>
            <css:AddRevocationValues binary="true"/>
            <css:AddTimeStampValues binary="true"/>
         </OptionalInputs>
         <InputDocuments>
            <Document>
            <Base64Data MimeType="application/pdf">JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9DcmVhdGlvbkRhdGUoRDoyMDIxMDgwNjEwMjcwMSkvQ3JlYXRvcihQREZpdW0pL1Byb2R1Y2VyKFBERml1bTsgbW9kaWZpZWQgdXNpbmcgaVRleHRTaGFycJIgNS41LjEzLjEgqTIwMDAtMjAxOSBpVGV4dCBHcm91cCBOViBcKEFHUEwtdmVyc2lvblwpKS9Nb2REYXRlKEQ6MjAyMTA5MjMwNjI2MTYrMDAnMDAnKT4</Base64Data>
          </Document>
         </InputDocuments>
      </VerifyRequest>
   </soapenv:Body>
</soapenv:Envelope>

```

### Sample Response

```xml
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<dss:VerifyResponse xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xm lns:css="http://www.safelayer.com/TWS" xmlns:dss="http://www.docs.oasis-open.o rg/dss/2004/06/oasis-dss-1.0-core-schema-wd-27.xsd" xmlns:xades="http://uri.et si.org/01903/v1.2.2#" Profile="urn:safelayer:tws:dss:1.0:profiles:pdf:1.0:veri fy" RequestID="9f116d3821d805702aaa" >
<dss:Result>
<dss:ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Succes s</dss:ResultMajor>
<dss:ResultMinor>urn:oasis:names:tc:dss:1.0:resultminor:ValidS ignature_OnAllDocuments</dss:ResultMinor>
</dss:Result>
<dss:OptionalOutputs>
<dss:SigningTime ThirdPartyTimestamp="false">2018-11-21T08:39: 45Z</dss:SigningTime>
<dss:SignerIdentity Format="urn:oasis:names:tc:SAML:1.1:nameid
-format:X509SubjectName">CN=Alexandros Monastiriotis + OID.2.5.4.5=#130F37834 313938353430343039313738, OU=UAE PASS, O=UAE Government, L=Dubai, C=AE</dss:Si
gnerIdentity>
<css:TrustInfo TrustLabel="" TrustLevel="0"/>
<css:TrustInfoSummary TrustLevel="0" />
<css:VerifyingPolicy xmlns:css="http://www.safelayer.com/TWS">
<css:Identifier Qualifier="OIDAsURN">urn:uae:tws:verificat ion:policy:digitalid</css:Identifier>
</css:VerifyingPolicy>
<css:ValidationPolicy xmlns:css="http://www.safelayer.com/TWS"
>
<css:Identifier Qualifier="OIDAsURN">urn:uae:tws:validation:policy:digitald</css:Identifier>
</css:ValidationPolicy>
<css:PdfFieldLabel>sign_091f1423</css:PdfFieldLabel>
<css:NumberPdfSignatures>1</css:NumberPdfSignatures>
</dss:OptionalOutputs>
</dss:VerifyResponse>

```


# Postman Collection for Digital Signature

### Postman Collection

{% file src="/files/3d4eQOL5g6CAqZNQInbJ" %}

### Postman Walkthrough

{% content-ref url="/pages/-Mkl4beTAtV-FmNQz-hz" %}
[Digital Signature Postman Walkthrough](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/postman-collection-for-digital-signature/digital-signature-postman-walkthrough-1)
{% endcontent-ref %}


# Digital Signature Postman Walkthrough

{% file src="/files/-Mkl4qei8YLXjXazj-Pk" %}
Signature Postman
{% endfile %}


# Verification API Integration

The purpose of this is to share the details and guidelines to perform verification of document signature done previously using UAE PASS platform.

UAE PASS offers API and a process for performing the digital signature on PDF document. It also offers the service for verifying the document signature. Document Signature verification service entails single synchronous SOAP based web service call.

## Glossary

| Acronym | Form                          |
| ------- | ----------------------------- |
| SOAP    | Simple Object Access Protocol |


# Web Service Details

## SOAP Gateway Endpoint

| Endpoint   | URL                                                 |
| ---------- | --------------------------------------------------- |
| Staging    | `https://stg-id.uaepass.ae/trustedx-gw/SoapGateway` |
| Production | `https://id.uaepass.ae/trustedx-gw/SoapGateway`     |

## Transport Headers to invoke SOAP Service

`HEAD` `https://stg-id.uaepass.ae/trustedx-gw/SoapGateway`

#### Headers

| Name         | Type   | Description                                             |
| ------------ | ------ | ------------------------------------------------------- |
| TwsAuthN     | string | urn:safelayer:tws:policies:authentication:oauth:clients |
| SOAPAction   | string | Verify                                                  |
| Content-Type | string | text/xml                                                |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

### Request

Below here is the SOAP template with place holder inside braces to be provided as per entity configuration and requirements:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xm 
lns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/X MLSchema-instance">
    <soapenv:Header>
        <wsse:Security soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next " soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/0 1/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <wsse:UsernameToken> 
                <wsse:Username>{Client ID as shared to SP}</wsse:Username>
                <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis- 200401-wss-username-token-profile-1.0#PasswordText">{Client Secret as shared t o SP} </wsse:Password>
            </wsse:UsernameToken>
        </wsse:Security>
    </soapenv:Header>
    <soapenv:Body>
        <VerifyRequest Profile="urn:safelayer:tws:dss:1.0:profiles:pdf:1.0:verif y" RequestID="{Random request ID for reference}" xmlns="http://www.docs.oasis- open.org/dss/2004/06/oasis-dss-1.0-core-schema-wd-27.xsd">
            <OptionalInputs>
                <ns1:ReturnSignerIdentity binary="true" xmlns:ns1="http://www.safe layer.com/TWS"/>
            </OptionalInputs>
            <InputDocuments>
                <Document> 
                    <Base64Data MimeType="application/pdf">
                        {Base64 encoded signed PDF document}
                    </Base64Data>
                </Document>
            </InputDocuments>
        </VerifyRequest>
    </soapenv:Body>
</soapenv:Envelope>
```

### Sample Request/Response (with Sample Data)

The integration team can try below request in any SOAP service testing tool (e.g. SOAPUI, PostMan etc.) by replacing the username password as provided by UAEPASS onboarding team.&#x20;

<mark style="color:green;">`POST`</mark> `stg-id.uaepass.ae/trustedx-gw/SoapGateway`

HTTP/1.1

#### Headers

| Name         | Type   | Description                                             |
| ------------ | ------ | ------------------------------------------------------- |
| TwsAuthN     | string | urn:safelayer:tws:policies:authentication:oauth:clients |
| SOAPAction   | string | Verify                                                  |
| Content-Type | string | text/xml                                                |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

### Request Sample

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/X MLSchema-instance">    <soapenv:Header>
        <wsse:Security soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next " soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/0 1/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <wsse:UsernameToken> 
                <wsse:Username>XXXXXXX</wsse:Username>
                <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis- 200401-wss-username-token-profile-1.0#PasswordText">XXXXXXXX</wsse:Password>
            </wsse:UsernameToken>
        </wsse:Security>
    </soapenv:Header>
    <soapenv:Body>
        <VerifyRequest Profile="urn:safelayer:tws:dss:1.0:profiles:pdf:1.0:verif y" RequestID="9f116d3821d805702aaa" xmlns="http://www.docs.oasis-open.org/dss/ 2004/06/oasis-dss-1.0-core-schema-wd-27.xsd">
            <OptionalInputs>
            <ns1:ReturnSignerIdentity binary="true" xmlns:ns1="http://www.safelay er.com/TWS"/>
            </OptionalInputs>
            <InputDocuments>
                <Document>
                    <Base64Data MimeType="application/pdf">
                        {Base64 encoded signed PDF document}
                    </Base64Data>
                </Document>
            </InputDocuments>
        </VerifyRequest>
    </soapenv:Body>
</soapenv:Envelope>  
            
                                
```

### Response Sample

```xml
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Body>
        <dss:VerifyResponse xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xm lns:css="http://www.safelayer.com/TWS" xmlns:dss="http://www.docs.oasis-open.o rg/dss/2004/06/oasis-dss-1.0-core-schema-wd-27.xsd" xmlns:xades="http://uri.et si.org/01903/v1.2.2#" Profile="urn:safelayer:tws:dss:1.0:profiles:pdf:1.0:veri fy" RequestID="9f116d3821d805702aaa" >
            <dss:Result>
                <dss:ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Succes s</dss:ResultMajor>
                <dss:ResultMinor>urn:oasis:names:tc:dss:1.0:resultminor:ValidS ignature_OnAllDocuments</dss:ResultMinor>
            </dss:Result>
            <dss:OptionalOutputs>
                <dss:SigningTime ThirdPartyTimestamp="false">2018-11-21T08:39: 45Z</dss:SigningTime>
                <dss:SignerIdentity Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName">CN=Alexandros Monastiriotis + OID.2.5.4.5=#130F373834 313938353430343039313738, OU=UAE PASS, O=UAE Government, L=Dubai, C=AE</dss:SignerIdentity>
                <css:TrustInfo TrustLabel="" TrustLevel="0"/>
                <css:TrustInfoSummary TrustLevel="0"/>
                <css:VerifyingPolicy xmlns:css="http://www.safelayer.com/TWS">
                    <css:Identifier Qualifier="OIDAsURN">urn:uae:tws:verificat ion:policy:digitalid</css:Identifier>
                </css:VerifyingPolicy>
                <css:ValidationPolicy xmlns:css="http://www.safelayer.com/TWS">
                    <css:Identifier Qualifier="OIDAsURN">urn:uae:tws:validation:policy:digitalid</css:Identifier>
                </css:ValidationPolicy>
                <css:PdfFieldLabel>sign_091f1423</css:PdfFieldLabel>
                <css:NumberPdfSignatures>1</css:NumberPdfSignatures>
            </dss:OptionalOutputs>
        </dss:VerifyResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```


# Postman Collection for Signature Verification API

{% file src="/files/-Mkp4GP-hp84qZvWpqrt" %}
Verify Postman Collection
{% endfile %}


# Digital Signature (Multiple Document)

Next steps can be used to implement multiple document signing.


# Signing Guide

This section will provide details and guidelines to perform the Digital Signing on Bulk of PDF Documents using the digital identity issued to individual for using UAE PASS.

## Description

UAE PASS offers API and a process for performing the Bulk PDF document signing. On a high level this operation is requested by a document signature portal or application (mobile/web) by entity (or user itself) on behalf of a user who logs in to the portal or application after authenticating in UAE PASS and completes the signing process.

### Eligibility of Digital Signature Feature Based on User Account Types

* **SOP1: Basic Unverified Account**

User account is unverified, only email Id and mobile number are verified. User does not have access to digital signature and data/document sharing capability of UAE PASS.

* **SOP2: Verified Account from Smart Pass / Dubai ID**

User account is verified. User digital signature is advanced level, and user can use digital signing feature only if advanced level signing is allowed through the implementation.

* **SOP3: Verified Account**

User account is verified. User digital signature is qualified level and has access to digital signing feature.

## Pre-Requisites

* <mark style="color:green;">**Using UAE PASS Authentication before prompting users to Sign documents with UAE PASS is mandatory to verify if the same user logged in is signing the document.**</mark>

## Limitations

* Bulk PDF signing capability is offered by an individual (not eSeals) i.e. a user needs to sign once for multiple documents requested to sign.
* The use case is fit for document of same or different type and this service allows signature appearance at any location or page number on PDF documents

### &#x20;**Signing the document entails seven steps:**&#x20;

{% content-ref url="/pages/-Mk5YUO713RPLdQ7Bvqr" %}
[1. Token](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/1.-obtaining-the-token-for-accessing-the-signature-operations)
{% endcontent-ref %}

{% content-ref url="/pages/AgOKb0mbzunOfMV2L3lp" %}
[2.Create Documents](/feature-guides/signature-integration-guide/digital-signature-multiple-document/signing-guide/untitled/2.create-documents)
{% endcontent-ref %}

{% content-ref url="/pages/CDeobfryqOnmBRmgAT4y" %}
[3. Create Signer Process](/feature-guides/signature-integration-guide/digital-signature-multiple-document/signing-guide/untitled/2.-creating-the-document-signature-process)
{% endcontent-ref %}

{% content-ref url="/pages/bmzzYtzmBa0pi00EyB6l" %}
[4. Sign Document](/feature-guides/signature-integration-guide/digital-signature-multiple-document/signing-guide/untitled/3.-executing-the-document-signature-process)
{% endcontent-ref %}

{% content-ref url="/pages/idzFXWnNHE8MGLaooawJ" %}
[5. Obtaining Document](/feature-guides/signature-integration-guide/digital-signature-multiple-document/signing-guide/untitled/4.-obtaining-the-signed-document)
{% endcontent-ref %}

{% content-ref url="/pages/g0mcqsyF81owzBo2y0bN" %}
[6. LTV Configuration](/feature-guides/signature-integration-guide/digital-signature-multiple-document/signing-guide/untitled/ltv-configuration)
{% endcontent-ref %}

{% content-ref url="/pages/dpprDJbMzf1nhK8PBUTq" %}
[7. Deleting Document](/feature-guides/signature-integration-guide/digital-signature-multiple-document/signing-guide/untitled/5.-deleting-the-document-signature-process)
{% endcontent-ref %}

### Sample Successful Digital signature printed in the pdf document

<div align="left"><figure><img src="/files/f2WMC0fWpYsxSg1JIF9V" alt=""><figcaption></figcaption></figure></div>


# Endpoints

Below are the standard endpoints for Staging and Production Environment:

**Staging**

<table><thead><tr><th width="182.66955222867227">Endpoints</th><th>URL</th></tr></thead><tbody><tr><td>Get Signing Access Token</td><td><a href="https://stg-id.uaepass.ae/trustedx-authserver/oauth/main-as/token"><code>https://stg-id.uaepass.ae/trustedx-authserver/oauth/main-as/token</code></a></td></tr><tr><td>Create Document ID</td><td><a href="https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents"><code>https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents</code></a></td></tr><tr><td>Create Sign Process</td><td><a href="https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes"><code>https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes</code></a></td></tr><tr><td>Get Signature Status</td><td><a href="https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/%7bAdd%20signer%20ProcessId%7d/result"><code>https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/{Add signer ProcessId}/result</code></a></td></tr><tr><td>Fetch Signed Document</td><td><a href="https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/%7bAdd%20documentId%7d/content"><code>https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/{Add documentId}/content</code></a></td></tr><tr><td>Delete Sign Process</td><td><a href="https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/{AddsignerProcessId}/">https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/{AddsignerProcessId<code>}</code></a></td></tr></tbody></table>

**Production**

| Endpoints                | URL                                                                                                                                                                                                               |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Get Signing Access Token | [`https://id.uaepass.ae/trustedx-authserver/oauth/main-as/token`](https://id.uaepass.ae/trustedx-authserver/oauth/main-as/token)                                                                                  |
| Create document ID       | [`https://id.uaepass.ae/trustedx-resources/esignsp/v2/documents`](https://id.uaepass.ae/trustedx-resources/esignsp/v2/documents)                                                                                  |
| Create Sign Process      | <https://id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes>                                                                                                                                            |
| Get Signature Status     | [https://id.uaepass.ae/trustedx-resources/esignsp/v2/signer\_processes/{Add signer ProcessId}/result](https://id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/%7bAdd%20signer%20ProcessId%7d/result) |
| Fetch Signed Document    | [https://id.uaepass.ae/trustedx-resources/esignsp/v2/documents/{Add documentId}/content](https://id.uaepass.ae/trustedx-resources/esignsp/v2/documents/%7bAdd%20documentId%7d/content)                            |
| Delete Sign Process      | <https://id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/{AddsignerProcessId}/>                                                                                                                      |

**Production**

{% hint style="info" %}
Note: Following fields “Add signer ProcessId”, “Add documentId” which are also highlighted above needs to be fetched from the output of “Create Sign Process Endpoint”. Details of the same has been illustrated below as a part of [create ](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/2.-creating-the-document-signature-process)and [delete ](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/5.-deleting-the-document-signature-process)signature process.&#x20;
{% endhint %}


# Document Signing Steps

### Here are the articles in this section:

{% content-ref url="/pages/TWRt0q3NFJQhy8va1csu" %}
[1. Token](/feature-guides/signature-integration-guide/digital-signature-multiple-document/signing-guide/untitled/1.-obtaining-the-token-for-accessing-the-signature-operations)
{% endcontent-ref %}

{% content-ref url="/pages/AgOKb0mbzunOfMV2L3lp" %}
[2.Create Documents](/feature-guides/signature-integration-guide/digital-signature-multiple-document/signing-guide/untitled/2.create-documents)
{% endcontent-ref %}

{% content-ref url="/pages/CDeobfryqOnmBRmgAT4y" %}
[3. Create Signer Process](/feature-guides/signature-integration-guide/digital-signature-multiple-document/signing-guide/untitled/2.-creating-the-document-signature-process)
{% endcontent-ref %}

{% content-ref url="/pages/bmzzYtzmBa0pi00EyB6l" %}
[4. Sign Document](/feature-guides/signature-integration-guide/digital-signature-multiple-document/signing-guide/untitled/3.-executing-the-document-signature-process)
{% endcontent-ref %}

{% content-ref url="/pages/g0mcqsyF81owzBo2y0bN" %}
[6. LTV Configuration](/feature-guides/signature-integration-guide/digital-signature-multiple-document/signing-guide/untitled/ltv-configuration)
{% endcontent-ref %}

{% content-ref url="/pages/dpprDJbMzf1nhK8PBUTq" %}
[7. Deleting Document](/feature-guides/signature-integration-guide/digital-signature-multiple-document/signing-guide/untitled/5.-deleting-the-document-signature-process)
{% endcontent-ref %}


# 1. Token

Obtaining the Token for Accessing the Signature Operations

Firstly, the document signature application/portal calls the UAEPASS API to obtain the access token using client credentials issued to them.

<mark style="color:green;">`POST`</mark> <https://stg-id.uaepass.ae/trustedx-authserver/oauth/main-as/token>

#### Headers

<table data-full-width="false"><thead><tr><th width="750">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>Authorization</td><td>string</td><td>Basic ZG9jc2lnbjpkZW1vZGVtbw==</td></tr><tr><td>Content-Type</td><td>string</td><td>application/x-www-form-urlencoded</td></tr><tr><td>grant_type </td><td>string</td><td>client_credentials</td></tr><tr><td>scope</td><td>string</td><td>urn:safelayer:eidas:sign:process:document</td></tr></tbody></table>

{% tabs %}
{% tab title="200 Content-Type: application/json;charset=utf-8
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache" %}

```
{
"access_token" : "{string}" 
"token_type" : "bearer", 
"expires_in" : 300

```

{% endtab %}
{% endtabs %}


# 2.Create Documents

After obtaining the access token in previous step, the portal/application lets the user choose the documents to be signed. Either by letting them upload the documents to the portal or select documents that the portal already has access to. Next, the portal creates each of the Document resources of the API by sending the PDF document. The portal must send a request to create a document signature process operation for each of the documents.

<mark style="color:green;">`POST`</mark> **<https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents>**

#### Headers

| Name                                            | Type   | Value                                                                  |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------- |
| Auhtorization                                   | String | Bearer fd1d9c5fc74fad4acc02eed62a81caf3d5d5a2017a18a253380fc18f2918574 |
| Content-Type                                    | String | multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW    |
| Postman-Token<mark style="color:red;">\*</mark> | String | 0cb4e517-8db9-473c-7b14-0ca2555bc199                                   |

#### Body

| Name     | Type   | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| signers  | String | <p>\[{ "signature\_policy\_id": "urn:safelayer:eidas:policies:sign:document:pdf", "parameters": { "type": "pades-baseline", "signature\_field": { "name": "Sign1", "location": { "page": { "number": "2" }, "rectangle": { "x": 100, "y": 50, "height": 150, "width": 400 } }, "appearance": { "signature\_details": { "font": { "size": 15, "style": "italic",<br>"embed": true }, "details": \[{ "type": "subject", "title": "Signer Name: " }, { "type": "date", "title": "Signature Date: " }] } } } } }]</p> |
| document | String | file1.pdf                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

{% code overflow="wrap" fullWidth="false" %}

```json
[{ "signature_policy_id": "urn:safelayer:eidas:policies:sign:document:pdf", "parameters": {
 "type": "pades-baseline",
 "signature_field": 
 {
  "name": "Sign1", 
  "location": {
   "page": {
    "number": "2" 
    }, 
    "rectangle":
     {
      "x": 100, "y": 50, "height": 150, "width": 400 
      } 
      },
   "appearance":
    { 
    "signature_details": 
    {
     "font": 
    {
     "size": 15, "style": "italic",
"embed": true 
},
 "details":
 [{ 
 "type": "subject", "title": "Signer Name: "
  },
  { 
  "type": "date", "title": "Signature Date: " 
  }]
   } 
   }
    }
     } 
     }]
```

{% endcode %}

In response to each request, the server responds with a message like the following:

**Response**

{% tabs %}
{% tab title="201" %}

```json
{
    "id": "t2mtk7bsp5vq8i1e3rqb6aejab1ivia5",
    "self": "https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/t2mtk7bsp5vq8i1e3rqb6aejab1ivia5",
    "signers": [
        {
            "id": "65lrfbflu2uilclpmvvv0nmucdadsgsg",
            "self": "https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/t2mtk7bsp5vq8i1e3rqb6aejab1ivia5/signers/65lrfbflu2uilclpmvvv0nmucdadsgsg"
        }
    ]
}

```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}


# 3. Create Signer Process

Creating the Document Signature Process

The portal requests the creation of the PDF document batch signature process by sending the following message to the UAE PASS using the signature services API. This API call will create a signing process at UAE PASS end.

<mark style="color:green;">`POST`</mark> <https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes>

#### Headers

| Name                                            | Type   | Description                          |
| ----------------------------------------------- | ------ | ------------------------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer \<token>                      |
| Cache-Control<mark style="color:red;">\*</mark> | string | no-cache                             |
| Postman-Token<mark style="color:red;">\*</mark> | string | 0cb4e517-8db9-473c-7b14-0ca2555bc199 |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json                     |

#### Response

{% tabs %}
{% tab title="201 If the request is successfully processed, UAE PASS creates the signature process for the document and responds to the document signature portal with the following HTTP message.
Location: <https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/sp_c4eed0a1f478f72454803695d53c4c52> Content-Type: application/json" %}

```
{
    "process_type": "urn:safelayer:eidas:processes:document:sign:esigp",
    "id": "hrcmc4pr78dt4s35jlbi4nmdrler4nn2",
    "self": "https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/hrcmc4pr78dt4s35jlbi4nmdrler4nn2",
    "tasks": {
        "pending": [
            {
                "type": "UserBrowserTask",
                "id": "dtvnbg6pbmaec4a35tlpnt1krs27hve1",
                "url": "https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/ui?signerProcessId=hrcmc4pr78dt4s35jlbi4nmdrler4nn2"
            }
        ]
    },
    "documents": [
        {
            "id": "c7mrogv8sqersqfj4sj7q21ucs1d3t4r",
            "url": "https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/c7mrogv8sqersqfj4sj7q21ucs1d3t4r",
            "content": "https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/c7mrogv8sqersqfj4sj7q21ucs1d3t4r/content"
        },
        {
            "id": "afa9gmord6dh6vhlvp1s533fs5fn8tui",
            "url": "https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/afa9gmord6dh6vhlvp1s533fs5fn8tui",
            "content": "https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/afa9gmord6dh6vhlvp1s533fs5fn8tui/content"
        }
    ]
}

```

{% endtab %}
{% endtabs %}

#### Request Body

```json
{
              "process_type": "urn:safelayer:eidas:processes:document:sign:esigp",
              "labels": [
                             [
                                           "digitalid",
                                           "server",
                                           "qualified"
                             ]
              ],
"documents": [
        {
            "id":"ieedah0mrjshgpblmt418l2m4rh8tlrd"
        },
        {
            "id":"g6do7ak05v3mod6i5sti3v33kdf0al9a"
        }
        ]
        ,

              "ui_locales": [
                             "en_US"
              ],
              "finish_callback_url": "http://localhost:8080/test",
              "views": {
                             "document_agreement": {
                                           "skip_server_id": "true"
                             }
              },
              "timestamp": {
                             "provider_id": "urn:uae:tws:generation:policy:digitalid"
              }
}

```

UAEPASS communicates with the signature portal, that successfully creates the signature process and that must redirects the user's browser to [https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/ui?signerProcessId=sp\_c4eed0a1f478f72454803695d53c4c5](https://qa-id.uaepass.ae/trustedx-resources/esignsp/v2/ui?signerProcessId=sp_c4eed0a1f478f72454803695d53c4c5) (tasks.pending.url) for this process to continue.&#x20;

It also communicates to the signature portal that obtain the signed document it must access [https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/dc\_9ee0990055818516249f28558e1b256b/content](https://qa-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/dc_9ee0990055818516249f28558e1b256b/content) (i.e., the URL resulting from concatenating /content to the URL specified in documents\[0].If signing the same document twice, make sure that unique value is passed for the name parameter in process type of request body as below:


# 4. Sign Document

Executing the Document Signature Process

The portal orders that the signature process be executed via the browser.&#x20;

The URL to which the browser is redirected must be extracted from the JSON response from the previous operation i.e. creation of document signature process. Specifically, the redirect URL is extracted from the URL field of the only element currently contained in the tasks.pending array of a recently created signature process (an element whose type is always UserBrowserTask). The execution of the signature process of a document is finished by sending a redirect response to the application/portal browser with which the user requested the signature.

<mark style="color:blue;">`GET`</mark> <https://stg-id.uaepass.ae/trustedx-resources/esigp/v1/signatures/{signature_id}/result>

#### Path Parameters

| Name            | Type   | Description                                                         |
| --------------- | ------ | ------------------------------------------------------------------- |
| signerProcessId | string | Identifier of the signature creation process whose result you want. |

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | Bearer \<token> |

{% tabs %}
{% tab title="302 If the operation is performed successfully, the body contains a JSON object with the following structure
{
"status": {string},
"details": {
"message": {string}
}
}

status (required):
Result of the document signature process:

* "finished": The process finished after all the documents were correctly signed.
* "failed": The process finished but no document was signed owing to an error.
* "failed\_documents": The process finished. Some of the documents were signed, but not all.
* "canceled": The process finished but no document was signed because the process was canceled.

details.message (Optional):
Additional information on the result of the document signature process.

Status of the finalized signature creation process (finished, failed or canceled):

* finished: The process has finalized after having successfully created the signature.
* failed: The process has terminated without being able to create the signature because an error occurred.
* canceled: The process terminated without a signature having been created because it was canceled.
* "failed\_documents": The process finished. Some of the documents were signed, but not all. " %}

```
Location: https://localhost:8080/callback?status=finished&signer_process_id=sp_c4eed0a1f478f72454803695d53c4c52
```

{% endtab %}
{% endtabs %}

> Example:\
> GET /trustedx-resources/esigp/v1/signatures/123-1234567/result HTTP/1.1 \
> Authorization: Bearer mF\_9.B5f-4.1JqM

### Response&#x20;

If the operation is performed successfully, the body contains a JSON object with the following structure

```
{
"status": {string}, "details": { "message": {string}}
}
```

| Property        | Usage    |                                                                                                                                                                                                                                                |
| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status          | Required | <p>Result of the document signature process:</p><p> </p><ul><li>"finished": The process finished after all the documents were correctly signed.</li><li>"failed": The process finished but no document was signed owing to an error.</li></ul> |
| details.message | Optional | Additional information on the result of the document signature process.                                                                                                                                                                        |


# 5. Obtaining Document

Obtaining the Signed Document

Following the [previous step](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/3.-executing-the-document-signature-process), the signature portal sends the following message to UAEPASS to obtain the signed PDF document.

## Obtain Signed PDF Document

<mark style="color:blue;">`GET`</mark> <https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/documents/{document_id}/content>

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | Bearer \<token> |

{% tabs %}
{% tab title="200 Note that for the sake of readability, {pdfSigned} replaces the binary content of the signed PDF." %}

```
Content-Type: application/pdf 

{pdfSigned}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Note that the portal demonstrates its authorization for obtaining the signed document by including the access token (403e...e7b3) in the Authorization header.&#x20;

Also note that the URL of the document requested is created by adding /content to the URL specified in the response received when the signature process for the document was created (the document\[0].url property of the JSON object contained in the response)
{% endhint %}


# 6. LTV Configuration

The purpose of this is to share the details and guidelines to perform the LTV -Long Term validations on PDF Document using the LTV configuration API issued to entity/organizations with UAEPASS.

### Description

UAEPASS offers API and a process for performing the LTV signature on documents on a high level, this operation is requested by a LTV portal or application (mobile/web) by an authorized user of the entity on behalf of that entity. \
LTV Long Term validation the document entails single synchronous SOAP based web service call.&#x20;

When LTV is enabled, the certificates sign-time status is captured and stored inside the PDF document. This is indicated within the signature details if it is LTV enabled or not. This verification certificate remains in the file itself so that its validity can be determined even at some later date, regardless of whether the certificate has expired, been revoked, or the issuing authority no longer exists. Because the record is stored inside the signed document, it is also authenticated by the document’s signature, further reducing chances for error or fraud.&#x20;

LTV helps reduce dependencies on external systems and reduces the potential for future ambiguity around expired or revoked certificates.&#x20;

LTV signature validations are done by PAdES (PDF Advanced Electronic Signatures) is a set of restrictions and extensions to PDF and ISO 32000-1 making it suitable for Advanced Electronic Signature. PAdES recognizes that digitally-signed documents may be used or archived for many years – even many decades. At any time in the future, in spite of technological and other advances, it must be possible to validate the document to confirm that the signature was valid at the time it was signed.&#x20;

When the user signs a document, the digital signature application also requests and embeds within their signature a secure timestamp from a trusted Time Stamp Authority (TSA). The timestamp returned by the TSA is digitally signed by the TSA so that it can be independently authenticated and trusted; it is also linked to the original signed document so it cannot be used with some other document. The embedded timestamp provides independent proof of the time of signing.&#x20;

UAEPASS digital signature application also contacts the appropriate Validation Authority (VA) to retrieve the certificate status for the signer’s certificate. The certificate status OCSP response is provided by the VA and provides an authoritative view on whether the certificate is currently trusted. UAEPASS digital signature application also embeds this certificate status information inside the signature for future verification by anyone.

{% hint style="info" %}
LTV implementation is mandatory after digital signature&#x20;
{% endhint %}


# Integration Web Services

### SOAP Gateway Endpoint

| Staging                                                                                               | Production                                      |
| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [https://stg-id.uaepass.ae/trustedx-gw/SoapGateway](https://qa-id.uaepass.ae/trustedx-gw/SoapGateway) | <https://id.uaepass.ae/trustedx-gw/SoapGateway> |

## Transport Headers to invoke SOAP Service

<mark style="color:green;">`POST`</mark> `https://stg-id.uaepass.ae/trusted-gw/SoapGateway`&#x20;

#### Headers

| Name         | Type   | Description                                             |
| ------------ | ------ | ------------------------------------------------------- |
| TwsAuthN     | string | urn:safelayer:tws:policies:authentication:oauth:clients |
| SOAPAction   | string | Update                                                  |
| Content-Type | string | text/xml                                                |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

### Request

```markup
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- wssecurity-secext-1.0.xsd" soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="1">
<wsse:UsernameToken>
<wsse:Username>XXXX</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- username-token-profile-1.0#PasswordText">XXXXX</wsse:Password><!-- 9QWtRunFT3-->
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<VerifyRequest Profile="urn:safelayer:tws:dss:1.0:profiles:nonrep:1.0" RequestID="b22c97c6117fc3386f81" xmlns="http://www.docs.oasis- open.org/dss/2004/06/oasis-dss-1.0-core-schema-wd-27.xsd">
<OptionalInputs>
<ReturnUpdatedSignature Type="urn:oasis:names:tc:dss:1.0:profiles:XAdES: forms:ES-A"/>
<css:PdfFieldLabel>SFLY Signature 0</css:PdfFieldLabel>
</OptionalInputs>
<InputDocuments>
<Document>
<Base64Data MimeType="application/pdf">XXX</Base64Data
</Document>
</InputDocuments>
</VerifyRequest>
</soapenv:Body>
</soapenv:Envelope>
```

### Request Parameters

|              |                                                                                    |           |
| ------------ | ---------------------------------------------------------------------------------- | --------- |
| Username     | client\_id of the SP. To be shared by the respective onboarding team.              | Mandatory |
| PasswordText | Client\_secret of the SP. To be shared by the respective onboarding team.          | Mandatory |
| RequestID    | SP can pass the unique ID for tracking the request for one particular transaction. | Optional  |
| Base64Data   | Base64 encoded data of the document which is to be LTV signed.                     | Mandatory |

### Sample Request/Response (with sample data):

The integration team can try below request in any SOAP service testing tool (e.g. SOAPUI, PostMan etc.) by replacing the username password as provided by UAEPASS onboarding team.

<mark style="color:green;">`POST`</mark> `stg-id.uaepass.ae/trusted-gw/SoapGateway`&#x20;

HTTP/1.1

#### Headers

| Name         | Type   | Description                                                             |
| ------------ | ------ | ----------------------------------------------------------------------- |
| TwsAuthN     | string | <p>urn:safelayer:tws:policies:authentication:oauth:<br> clientsSOAP</p> |
| Action       | string | Verify                                                                  |
| Content-Type | string | text/xml                                                                |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

#### Request Sample

```xml
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance">
<soapenv:Header>
<wsse:Security soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- wssecurity-secext-1.0.xsd">
<wsse:UsernameToken>
<wsse:Username>XXXXX</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username- token-profile-1.0#PasswordText">XXXXX</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
  <VerifyRequest Profile="urn:safelayer:tws:dss:1.0:profiles:pdf:1.0:verify" RequestID="ba3810598a90af56a7e8" xmlns="http://www.docs.oasis-open.org/dss/2004/06/oasis-dss-1.0- core-schema-wd-27.xsd">
    <OptionalInputs>
      <ns1:AddCertificateValues binary="true" xsi:type="ns1:AddCertificateValuesType" xmlns:ns1="http://www.safelayer.com/TWS"/>
      <ns2:AddSignatureForm/>
      <css:AddRevocationValues binary="true"/>
      <css:AddTimeStampValues binary="true"/>
    </OptionalInputs>
    <InputDocuments>
      <Document>
        <Base64Data MimeType="application/pdf">JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUG FnZXMgMiAwIFIvTGFuZyhlbi1VUykgL1N0cnVjdFRyZWVSb290IDkgMCBSL01hcmtJbmZvPDwvTWFya2V kIHRydWU+Pj4+DQplbmRvYmoNCjIgMCBvYmoNCjw8L1R5cGUvUGFnZXMvQ291bnQgMS9LaWRzWyA zIDAgUl0gPj4NCmVuZG9iag0KMyAwIG9iag0KPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJj ZXM8PC9YT2JqZWN0PDwvSW1hZ2U1IDUgMCBSPj4vRXh0R1N0YXRlPDwvR1M3IDcgMCBSPj4vUHJv
        Y1NldFsvUERGL1RleHQvSW1hZ2VCL0ltYWdlQy9JbWFnZUldID4+L01lZGlhQm94WyAwIDAgNjEyIDc5Ml 0gL0NvbnRlbnRzIDQgMCBSL0dyb3VwPDwvVHlwZS9Hcm91cC9TL1RyYW5zcGFyZW5jeS9DUy9EZXZp Y2VSR0I+Pi9UYWJzL1MvU3RydWN0UGFyZW50cyAwPj4NCmVuZG9iag0KNCAwIG9iag0KPDwvRmlsd GVyL0ZsYXRlRGVjb2RlL0xlbmd0aCAxMTM+Pg0Kc3RyZWFtDQp4nBWKsQqDMBRF9wfvH+7skLwXrDEgDk2KOAgVB2cRcdJS+//QeIcznHNh32gaO8Q+QdoWzxRhu8lj/zF9mcTIvaAOgirTB4drY5oLnEwqajQXgda
        mQsh3V8JnW2I9mGx/LPv2QPpgZMJriPgDPogXfg0KZW5kc3RyZWFtDQplbmRvYmoNCjUgMCBvYmoNC jw8L1R5cGUvWE9iamVjdC9TdWJ0eXBlL0ltYWdlL1dpZHRoIDIvSGVpZ2h0IDIvQ29sb3JTcGFjZVsvSW5k ZXhlZC9EZXZpY2VSR0IgMSA8MDAwMDAwRkZGRkZGPl0gL0JpdHNQZXJDb21wb25lbnQgMS9JbnRlcn BvbGF0ZSBmYWxzZS9TTWFzayA2IDAgUi9MZW5ndGggMj4+DQpzdHJlYW0NCgAADQplbmRzdHJlYW0 NCmVuZG9iag0KNiAwIG9iag0KPDwvVHlwZS9YT2JqZWN0L1N1YnR5cGUvSW1hZ2UvV2lkdGggODQyL 0hlaWdodCAxNTQvQ29sb3JTcGFjZS9EZXZpY2VHcmF5L0JpdHNQZXJDb21wb25lbnQgMS9GaWx0ZXIv RmxhdGVEZWNvZGUvTGVuZ3RoIDExOTU+Pg0Kc3RyZWFtDQp4nO3ZS47cNhAAUNI0wCVzgjAHMaAc K6tQgQ/io0RH0S5bZccFIbo+LKql1sz0jDWDfKph9Mglqp6+JEttzAd9ho+CVFJJJZVUUkkllVRSSSWVVFJJ pX+JZOdXb+qmN0nx9dKg0jBU/CwshVHi7mX5h6TYN/bL+0rDLPGQ31dKi8RjUekfJUFHtBp5nj5Oetd7bye 96/O0k077iC24X/GolM+k00/aSVvDByWvkkr/Q8kXnlhVTrz0vokkWsYvkUJBaVioxUSzuC/GjbA6YIx6M8p5L 1UgYONQaQ00d3WlNBX+WlzGQKyVdwX+Tq2JrwV3wBWTvtZCTWGrkXN6aDjvpL9wS5BgFGlSwAhJBZ LBlhhACdc7kiKx8C3St1oDxiymp5y+cppNIhqkxCtAgtAiUmx5F5E4wUD7i5s0CaJ/ouRxW8p5Ki0oVc4P0oB EkyglBkSKlIAb4wndJFoBB5Y556mUQbLttIKUKl0ykhKmxIBIOFRT44xn6iDNmK5wzhNpGlBydUzt7NU59r MHy5kCIiW48tB4GorBTeQ6VTjAMcHhZ79yznup4I0J0mqCSKNb2l1u4R4qHGh3OV1UV+FmN5AziAQHXv BhSLOFu2TFnHd3+WIg1zDBlxtJgqZmbhL4rnBApLE1XhH7JNKET1jEvTS15TzpI1iCeJMg/ItIBVpxgCVUhy ngReKHtEkjHhBKuBnnPJGcSKZLpkleJOkjcBmkBSW6ml2iTsKK5F4tQXQnOZFM5chBwtVvlupOKijhMu36 qTS9IJUu1U2inecAS/5Goj59L/UdeUZyVSTDj8EmcaBJ+QJp6tJylJaDhMYPSKVLtUvYM1QOHCX4Hu8kT7 3f85Jtww/1e/NeokCb7C6blN4mGe7KuS8ve4kC10mJ8/P4tJcocJ0U+5jrWyfcJQpcJ3m+UNTR8IXqEg/Zl0m mj+5wXRaR+N7AwGMSZX9JijLmwuHlvYSBCyUr8wgcWPcSBi6UuKwmKR6leK0Uu+SPkt9LuDyMb5doD CXJrU2i/3GgSTc9LM1w7vu9ByTfJXuUrEgP9OXXSsv1Uj6VeDAZ5ntpfVn6tEnjJvGtMd5Ipc2NzqU+PD83P o1dmkWaKPFPHKA7U2YsuUUsfh2kzyKVc8lPrdJaLG1rqPbDxL9xgC8ZTgJSm1nCPNqjFDYJZ5Y/t5zuKS nL8wRh3p1h/gxTb5s5ELLFCwaB2mbL8C+OONW+lWbzu0ir+fVMCjC0ziTBjCLSKR6WL7bOoXAglEDSHK QCgE3qGFZbb6SUnVRvrvKPBUcp9qrGV65qoMstWCIVDngev+pW1VA1gV830lB7nWiPtUY/Jhk1XKvZQF qp2OVAG7/SVqk5Kf1upLjVVDLM3c+N+kjYjg7Ozor7mDngeD1ValyqUqXm9lLAMpxzmickU7li5zMw0rPDJf vMgTZ5gkCcWkWdqLivf99IvvJQhlJ6Qor9LYFnE5JkPBLTAmllPkecChRSM+b740YybcqBUuQdvvuly8okeX v/i501veKgAD+67QUJNba4fHhxG7Y3xu3R/S//eqeSSiqppJJKKqmkkkoqqaSSSiqppJJKKl0mfQfGpmwvDQ plbmRzdHJlYW0NCmVuZG9iag0KNyAwIG9iag0KPDwvVHlwZS9FeHRHU3RhdGUvQk0vTm9ybWFsL2Nh IDE+Pg0KZW5kb2JqDQo4IDAgb2JqDQo8PC9BdXRob3IoTW9oYW1tYWQgWXVzdWYgS2hhbikgL0NyZ WF0b3Io/v8ATQBpAGMAcgBvAHMAbwBmAHQArgAgAFcAbwByAGQAIAAyADAAMQA2KSAvQ3JlYXRp b25EYXRlKEQ6MjAxODEwMTMwMzE3NDArMDQnMDAnKSAvTW9kRGF0ZShEOjIwMTgxMDEzMDMxN zQwKzA0JzAwJykgL1Byb2R1Y2VyKP7/AE0AaQBjAHIAbwBzAG8AZgB0AK4AIABXAG8AcgBkACAAMgA
        wADEANikgPj4NCmVuZG9iag0KMTYgMCBvYmoNCjw8L1R5cGUvT2JqU3RtL04gOC9GaXJzdCA1Mi9Ga Wx0ZXIvRmxhdGVEZWNvZGUvTGVuZ3RoIDM0Mz4+DQpzdHJlYW0NCniclZJda8IwFIbvB/6Hc7ldpamrsy CCTGVDFGkLuxAvYnvWFttE0hT03y+nH7MwbwYlPV/vk5yT8FdwgL/B1Ac+Bu5NgLvgch98cCdT4A6MPZ vi4PmeTcOET2E2Y3uqdiBgIQsvQrLodkEWGl3HZlVgyRaxqUUR4dU8R1legf0MVgYSFdclSvMCbHMA5wh sn0JDms9HT/8DQwN5iHA7xP6P3u7KqeWAmra/R3K/VwttHgLGrbITDCoijRgoZVigCtyKC82PWJZkm6Ysj ZIihHH7A/xmd7avDd6Ad+i1ZUllkO1oWcnk7tAITurKQowN+0CRoG5t0vT2pyxyiWEm6IQUWEhLECZXsvO 1yb+FNRrvS+nzSakzW3bX1ESqDNG0w9iKWKuB/57ZdeAvc1GodBAIizzBQW27jy1LtSjZOk9rjV2vu7qsDv QYvft0+8s6wujpBwpmzsUNCmVuZHN0cmVhbQ0KZW5kb2JqDQoxOCAwIG9iag0KPDwvVHlwZS9YUmV mL1NpemUgMTgvV1sgMSA0IDJdIC9Sb290IDEgMCBSL0luZm8gOCAwIFIvSURbPDdDQTMxNTQxMDkw OTQ0NDY4QjQ3NjA5ODc1RTJBRjU2Pjw3Q0EzMTU0MTA5MDk0NDQ2OEI0NzYwOTg3NUUyQUY1Nj5d
        IC9GaWx0ZwMDA1NDAyNSAwMDAwMCBuIAowMDAwMDU0MDk5IDAwMDAwIG4gCjAwMDAwNTQyNzcgM DAwMDAgbiAKMDAwMDA3OTIxNSAwMDAwMCBuIAowMDAwMDU0MTQ2IDAwMDAwIG4gCjAwMDAw
        NzkwMzkgMDAwMDAgbiAKMDAwMDA3OTEzOCAwMDAwMCBuIAp0cmFpbGVyCjw8L1NpemUgNDkvU m9vdCAxIDAgUi9JbmZvIDggMCBSL0lEIFs8N2NhMzE1NDEwOTA5NDQ0NjhiNDc2MDk4NzVlMmFmNTY
        +PGEwN2RjZTMxM2RmMjc4YmJhZmE4NDEzODUzOWU5NTcwPl0vUHJldiAzMzc3NT4+CiVpVGV4dC0 1LjUuMTIKc3RhcnR4cmVmCjgwMjQwCiUlRU9GCg==
        </Base64Data>
      </Document>
    </InputDocuments>
  </VerifyRequest>
</soapenv:Body>
</soapenv:Envelope>


```

#### Response Sample

```markup
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<dss:SignResponse xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xmln
s:css="http://www.safelayer.com/TWS" xmlns:dss="http://www.docs.oasis-open.org
/dss/2004/06/oasis-dss-1.0-core-schema-wd-27.xsd" xmlns:xades="http://uri.etsi
.org/01903/v1.2.2#" Profile="urn:safelayer:tws:dss:1.0:profiles:pades:1.0:sign "
RequestID="b22c97c6117fc3386f81" >
<dss:Result>
<dss:ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Succes
s</dss:ResultMajor>
</dss:Result>
<dss:OptionalOutputs>
<dss:DocumentWithSignature>
<dss:XMLData>
<dss:Base64Data MimeType="application/pdf">JVBERi0xLjU
NCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFuZyhlbi1VUykgL 
1N0cnVjdFRyZWVSb290IDkgMCBSL01hcmtJbmZvPDwvTWFya2VkIHRydWU+Pj4+DQplbmRvYmoNCjI 
gMCBvYmoNCjw8L1R5cGUvUGFnZXMvQ291bnQgMS9LaWRzWyAzIDAgUl0gPj4NCmVuZG9iag0KMyAwI 
G9iag0KPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9YT2JqZWN0PDwvSW1hZ2U 
1IDUgMCBSPj4vRXh0R1N0YXRlPDwvR1M3IDcgMCBSPj4vUHJvY1NldFsvUERGL1RleHQvSW1hZ2VCL
0ltYWdlQy9JbWFnZUldID4+L01lZGlhQm94WyAwIDAgNjEyIDc5Ml0gL0NvbnRlbnRzIDQgMCBSL0d 
yb3VwPDwvVHlwZS9Hcm91cC9TL1RyYW5zcGFyZW5jeS9DUy9EZXZpY2VSR0I+Pi9UYWJzL1MvU3Ryd
JUVPRgo=</dss:Base64Data>
                    </dss:XMLData>
                </dss:DocumentWithSignature>
                <css:NumberPdfSignatures>2</css:NumberPdfSignatures>
            </dss:OptionalOutputs>
        </dss:VerifyResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


```

### Error Codes

| Code                                                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| urn:oasis:names:tc:dss:1.0: resultminor:NotAuthorized                       | The requester or the requested party is not authorized to perform this operation.                                                                                                                                                                                                                                                                                                                                                                         |
| urn:oasis:names:tc:dss:1.0: resultminor:NotSupported                        | The server does not recognize or support some aspect of the request.                                                                                                                                                                                                                                                                                                                                                                                      |
| urn:safelayer:dss:1.0: resultminor:PolicyViolation                          | The server cannot process the request owing to a service policy violation.                                                                                                                                                                                                                                                                                                                                                                                |
| urn:safelayer:dss:1.0:resultminor:SignerCertificateNotFound                 | Signer's certificate not found in the signature or in the verification request.                                                                                                                                                                                                                                                                                                                                                                           |
| urn:oasis:names:tc: dss:1.0:resultminor:NotSupported                        | The server cannot process the content of a valid element in the request owing to an unexpected error. The dss:ResultMessage element can include lower level information on the reasons for the error.                                                                                                                                                                                                                                                     |
| urn:safelayer:dss:1.0: resultminor:SigningError                             | The input data and parameters are correct, but the server cannot generate the signature requested owing to an unexpected error. The dss:ResultMessage element can include lower level information on the reasons for the error.                                                                                                                                                                                                                           |
| urn:oasis:names:tc:dss:1.0:resultminor: ValidSignature\_OnAllDocuments      | The signature or timestamp is valid and includes all the input documents indicated in the request.                                                                                                                                                                                                                                                                                                                                                        |
| urn:oasis:names:tc:dss:1.0:resultminor: ValidSignature\_NotAllDocuments     | There are multiple signatures or timestamps but not all are valid.                                                                                                                                                                                                                                                                                                                                                                                        |
| urn:oasis:names:tc:dss:1.0:resultminor: IncorrectSignature                  | <p>The signature cannot be verified (the</p><p> that comes with this result indicates the causes of the error)</p>                                                                                                                                                                                                                                                                                                                                        |
| urn:safelayer:dss:1.0: resultminor: IncorrectKeySelected                    | Signature not generated owing to the selection of an invalid key.                                                                                                                                                                                                                                                                                                                                                                                         |
| urn:safelayer:dss:1.0: resultminor: IncorrectAlgorithmIdentifier            | The selected signature algorithm is not supported.                                                                                                                                                                                                                                                                                                                                                                                                        |
| urn:safelayer:dss:1.0: resultminor: IncorrectFormatInData                   | Incorrect input data.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| urn:safelayer:tws:dss:1.0: profiles:resultminor: UntrustedKey:CA            | The signed message has not been modified but the signature key is not trusted (because the certification chain could not be built or because the CA certificate is not trusted).                                                                                                                                                                                                                                                                          |
| urn:safelayer:tws:dss:1.0: profiles:resultminor: UntrustedKey:Validity      | The signed message has not been modified and the certification chain is trusted. However, the signature key is not trusted because the certificate has expired and it cannot be verified that the signature was generated when the certificate was valid.                                                                                                                                                                                                 |
| urn:safelayer:tws:dss:1.0: profiles:resultminor: UntrustedKey:Status        | <p>The signed message has not been edited, the certification chain is trusted and the signature was generated with a valid certificate. However, the server could not verify that the signature key was valid. Either because the status information indicates that the signature was invalid or because the status information could not be queried. The</p><p> element of the XML message contains further information on the certificate's status.</p> |
| urn:safelayer:tws:dss:1.0: profiles:resultminor: IncorrectArchiveSignature  | <p>The archive signature cannot be verified (the</p><p> element indicates the causes of the error).</p>                                                                                                                                                                                                                                                                                                                                                   |
| urn:safelayer:tws:dss:1.0:profiles:resultminor:UntrustedKey:GoodWit hNoInfo | The signed message has not been edited, and the signature key is trusted. However, the status of all the certificates in the certification chain cannot be determined owing to a lack of revocation information in the long-term signature.                                                                                                                                                                                                               |


# Postman Collection for LTV

{% file src="/files/-Mkp4-3UeQzSfs8-6hN2" %}
LTV Postman Collection
{% endfile %}


# 7. Deleting Document

Deleting the Document Signature Process

After obtaining the [signed PDF document](/feature-guides/signature-integration-guide/digital-signature-single-document/signing-guide/untitled/4.-obtaining-the-signed-document), the document signature portal sends the following message to UAEPASS to delete the document signature process used.&#x20;

## Delete Document Signature

<mark style="color:red;">`DELETE`</mark> <https://stg-id.uaepass.ae/trustedx-resources/esignsp/v2/signer_processes/{process_id}>

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | Bearer \<token> |

{% tabs %}
{% tab title="204 UAEPASS deletes the document signature process and responds with the following message" %}

```
No content
```

{% endtab %}
{% endtabs %}


# Document Signature verification Process

UAE PASS document signature verification API offers for the signer’s identity verification through UAE PASS digital signature feature. On integrating the UAE PASS Document signature verification feature SP can validate the document singed time, signer details up to 3 years.

### SOAP Gateway Endpoint

| Staging                                                                                               | Production                                      |
| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [https://stg-id.uaepass.ae/trustedx-gw/SoapGateway](https://qa-id.uaepass.ae/trustedx-gw/SoapGateway) | <https://id.uaepass.ae/trustedx-gw/SoapGateway> |

## Transport Headers to invoke SOAP Service

<mark style="color:green;">`POST`</mark> `https://stg-id.uaepass.ae/trusted-gw/SoapGateway`&#x20;

#### Headers

| Name         | Type   | Description                                             |
| ------------ | ------ | ------------------------------------------------------- |
| TwsAuthN     | string | urn:safelayer:tws:policies:authentication:oauth:clients |
| SOAPAction   | string | Verify                                                  |
| Content-Type | string | text/xml                                                |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

### Request

```xml
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Header>
      <wsse:Security soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken>
            <wsse:Username>{client_id}</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">{client_secret}</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <VerifyRequest Profile="urn:safelayer:tws:dss:1.0:profiles:pdf:1.0:verify" RequestID="ba3810598a90af56a7e8" xmlns="http://www.docs.oasis-open.org/dss/2004/06/oasis-dss-1.0-core-schema-wd-27.xsd">
         <OptionalInputs>
            <ns1:AddCertificateValues binary="true" xsi:type="ns1:AddCertificateValuesType" xmlns:ns1="http://www.safelayer.com/TWS"/>
            <ns2:AddSignatureForm/>
            <css:AddRevocationValues binary="true"/>
            <css:AddTimeStampValues binary="true"/>
         </OptionalInputs>
         <InputDocuments>
            <Document>
            <Base64Data MimeType="application/pdf">JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9DcmVhdGlvbkRhdGUoRDoyMDIxMDgwNjEwMjcwMSkvQ3JlYXRvcihQREZpdW0pL1Byb2R1Y2VyKFBERml1bTsgbW9kaWZpZWQgdXNpbmcgaVRleHRTaGFycJIgNS41LjEzLjEgqTIwMDAtMjAxOSBpVGV4dCBHcm91cCBOViBcKEFHUEwtdmVyc2lvblwpKS9Nb2REYXRlKEQ6MjAyMTA5MjMwNjI2MTYrMDAnMDAnKT4</Base64Data>
          </Document>
         </InputDocuments>
      </VerifyRequest>
   </soapenv:Body>
</soapenv:Envelope>

```

### Request Parameter

| Name         | Description                                                                        | Required  |
| ------------ | ---------------------------------------------------------------------------------- | --------- |
| Username     | client\_id of the SP. To be shared by the respective onboarding team.              | Mandatory |
| PasswordText | Client\_secret of the SP. To be shared by the respective onboarding team.          | Mandatory |
| RequestID    | SP can pass the unique ID for tracking the request for one particular transaction. | Optional  |
| Base64Data   | Base64 encoded data of the document which is to be verified                        | Mandatory |

### Sample Request

```svg
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Header>
      <wsse:Security soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken>
            <wsse:Username>{client_id}</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">{client_secret}</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <VerifyRequest Profile="urn:safelayer:tws:dss:1.0:profiles:pdf:1.0:verify" RequestID="ba3810598a90af56a7e8" xmlns="http://www.docs.oasis-open.org/dss/2004/06/oasis-dss-1.0-core-schema-wd-27.xsd">
         <OptionalInputs>
            <ns1:AddCertificateValues binary="true" xsi:type="ns1:AddCertificateValuesType" xmlns:ns1="http://www.safelayer.com/TWS"/>
            <ns2:AddSignatureForm/>
            <css:AddRevocationValues binary="true"/>
            <css:AddTimeStampValues binary="true"/>
         </OptionalInputs>
         <InputDocuments>
            <Document>
            <Base64Data MimeType="application/pdf">JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9DcmVhdGlvbkRhdGUoRDoyMDIxMDgwNjEwMjcwMSkvQ3JlYXRvcihQREZpdW0pL1Byb2R1Y2VyKFBERml1bTsgbW9kaWZpZWQgdXNpbmcgaVRleHRTaGFycJIgNS41LjEzLjEgqTIwMDAtMjAxOSBpVGV4dCBHcm91cCBOViBcKEFHUEwtdmVyc2lvblwpKS9Nb2REYXRlKEQ6MjAyMTA5MjMwNjI2MTYrMDAnMDAnKT4</Base64Data>
          </Document>
         </InputDocuments>
      </VerifyRequest>
   </soapenv:Body>
</soapenv:Envelope>

```

### Sample Response

```xml
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<dss:VerifyResponse xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xm lns:css="http://www.safelayer.com/TWS" xmlns:dss="http://www.docs.oasis-open.o rg/dss/2004/06/oasis-dss-1.0-core-schema-wd-27.xsd" xmlns:xades="http://uri.et si.org/01903/v1.2.2#" Profile="urn:safelayer:tws:dss:1.0:profiles:pdf:1.0:veri fy" RequestID="9f116d3821d805702aaa" >
<dss:Result>
<dss:ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Succes s</dss:ResultMajor>
<dss:ResultMinor>urn:oasis:names:tc:dss:1.0:resultminor:ValidS ignature_OnAllDocuments</dss:ResultMinor>
</dss:Result>
<dss:OptionalOutputs>
<dss:SigningTime ThirdPartyTimestamp="false">2018-11-21T08:39: 45Z</dss:SigningTime>
<dss:SignerIdentity Format="urn:oasis:names:tc:SAML:1.1:nameid
-format:X509SubjectName">CN=Alexandros Monastiriotis + OID.2.5.4.5=#130F37834 313938353430343039313738, OU=UAE PASS, O=UAE Government, L=Dubai, C=AE</dss:Si
gnerIdentity>
<css:TrustInfo TrustLabel="" TrustLevel="0"/>
<css:TrustInfoSummary TrustLevel="0" />
<css:VerifyingPolicy xmlns:css="http://www.safelayer.com/TWS">
<css:Identifier Qualifier="OIDAsURN">urn:uae:tws:verificat ion:policy:digitalid</css:Identifier>
</css:VerifyingPolicy>
<css:ValidationPolicy xmlns:css="http://www.safelayer.com/TWS"
>
<css:Identifier Qualifier="OIDAsURN">urn:uae:tws:validation:policy:digitald</css:Identifier>
</css:ValidationPolicy>
<css:PdfFieldLabel>sign_091f1423</css:PdfFieldLabel>
<css:NumberPdfSignatures>1</css:NumberPdfSignatures>
</dss:OptionalOutputs>
</dss:VerifyResponse>

```


# Postman Collection for Multiple Document Signing.

Following postman collection and postman walk through will guide you on how to use the API collection to sign multiple documents using sandbox credentials.

### Postman Collection and Walk-through

{% file src="/files/iAw4N9kmR5zyRKdCMIiC" %}

{% file src="/files/ZsUCb3sxyPEfM9IIW7Ay" %}


# Hash Signing

The purpose of this document is to share the details and guidelines to perform the Digital Hash Signing of PDF Documents using the UAEPASS digital identity issued to individual and/or organizations.

### Here are the articles in this Section:

{% content-ref url="/pages/-MkkRcSpKEo07S1dhSG3" %}
[Introduction](/feature-guides/signature-integration-guide/hash-signing/introduction)
{% endcontent-ref %}

{% content-ref url="/pages/xBVVXrw0IdVlilmjhNv9" %}
[Hash Signing (Single Document)](/feature-guides/signature-integration-guide/hash-signing/hash-signing-single-document)
{% endcontent-ref %}

## **Glossary**

| **Term** | **Description**                 |
| -------- | ------------------------------- |
| GSB      | Government Service Bus          |
| SOAP     | Simple Object Access Protocol   |
| REST     | Representational state transfer |


# Introduction

UAEPASS provides a **"Hash Signing"** feature for digital document signing, ensuring a more secure method to sign PDF documents without the need to send them outside the organization's premises.

**Here's how it works:**&#x20;

When a user logs into a document signature portal or application through UAEPASS authentication, the entity requests the signing of a document from UAEPASS. The entity sends the document's hash to UAEPASS and UAEPASS signs the hash of the document to send it back to the entity in PKCS#1 format. Entity should embed the signed hash back into the document in PKCS#7 format. At the end user can view and download the signed document.

Below is the high-level architectural diagram of UAEPASS Hash Signing:

![Fig 1: High Level Architecture of UAEPASS Hash Signing](/files/-MkkRuwuVnYyGIsnSZpe)

![Fig 2 : Hash Signing Work Flow](/files/djGAPI8W8oqwudYXcAqf)

![Fig 3: Hash Signing Flow](/files/gnGgK2smrpEZceidNwmF)


# Hash Signing (Single Document)

<figure><img src="/files/ctLTTek3j9PfNrkxO1tt" alt=""><figcaption></figcaption></figure>


# Hash Signing (Java SDK Set Up)

UAEPASS offers Java SDK based hash signing that can be installed and used locally by service providers. Following guide provides more information on SDK based hash signing and how service providers can successfully integrate the feature.


# Quick Setup

## Pre-Requisites

**System Requirements:**

* OS 64-bit arch-type (Windows, Linux or Unix).
* Java Development Kit version 11/64-bit or later.

**Service requirements (Below are configurable):**

* Minimum memory 512 megabytes.
* Temp. directory with no restrictions. (Read/Write).

**Business requirement:**

* User who want to use this service should have **qualified signing certificate** , otherwise the user will not be able to reach the step of signing a document.
* For **Production deployment process** the SP need to be whitelisted their IP at DESC side to be able to access this URL&#x20;

  <https://ca-services.desc.gov.ae/adss/tsa&#x20>;
* In case of any SSL issues please import the DESC TSA root and intermediate certificates to resolve the error. The certificate needs to be imported in Java cacerts. In order to obtain the certificates please reach out to the onboarding/operations team.

## **Running service instructions:**

* Download .jar file along with .jks and .pem files that will be provided from UAEPASS.
* SP need to install the TSA certificate using below command:&#x20;

```sh
"keytool -importcert -file {file path} -keystore cacerts -keypass changeit -storepass changeit -noprompt -alias tsa_Staging"
```

* Get the TSA Staging certificate from respective onboarding team
* Please note that the TSA certificate needs to be installed in java cacerts for both the environments (staging and production).
* Execute the below command after verifying that you have Java 11+ successfully installed (you can check by executing command “java -version” in terminal window), values in red according to your environment values:

**Initiate the command to initialize the Jar (parameters to change as per environment):**&#x20;

```sh
java -Dtmp.dir=D:\Documents\StagingOnboarding\HashSigning\UtilityFiles2\UtilityFiles2 -DtrustStore.path=D:\Documents\StagingOnboarding\HashSigning\UtilityFiles2\UtilityFiles2\tsa-staging-tx-dev.jks -DparentCert.path=D:\Documents\StagingOnboarding\HashSigning\UtilityFiles2\UtilityFiles2\parentCertificate-stg.pem -Dtx/mp-rest/url=
https://stg-id.uaepass.ae
 -Dtx2/mp-rest/url=
https://stg-apis.uaepass.ae
 -Dtx.clientId=(SP specific client id) -Dtx.apiKey=(base64 endoded client id and secret) -Dtx.tokenRedirectUrlV2=
http://localhost:8089/v2/signature/token
 -Dtx.signIndenRedirectUrlV2=
http://localhost:8089/v2/signature/sign-identity
 -Dmax.allowed.file.size=52428800 -Dmax.allowed.files.count=10 -Dquarkus.http.port=8089 -Dquarkus.profile=staging -Xms512m -Xmx1G -jar digital-signature.jar
```

&#x20;

**List of elements in the above command:**

| Element                             | Description                                                                                                                                                                                                                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| *Dtmp.dir (mandatory)*              | <p><em>This is any temporary location with read/write access to store files during processing temporarily locally in client’s environment.</em></p><p><em>This will be cleaned automatically by utility</em></p>                                                                           |
| *DtrustStore.path(mandatory)*       | *directory of .jks file(keystore which contains certificates as per the environment)* File will be provided by UAE PASS Onboarding team                                                                                                                                                    |
| *DparentCert.path(mandatory)*       | *directory of .pem file(used to store SSL certificates and their associated private keys as per the environment)*&#x46;ile will be provided by UAE PASS Onboarding team                                                                                                                    |
| *Dquarkus.profile(mandatory)*       | *Target environment of UAE PASS (staging or production)*                                                                                                                                                                                                                                   |
| *Dtx.clientId(mandatory)*           | *Client\_id (given by Onboarding team and automatically included) - To be used as per the environment*                                                                                                                                                                                     |
| -Dtx/mp-rest/url(mandatory)         | UAEPASS Base URL domain url depending on environment i.e. staging= [<mark style="color:green;">https://stg-id.uaepass.ae</mark>](https://stg-id.uaepass.ae/) , production=[<mark style="color:green;">https://id.uaepass.ae</mark>](https://id.uaepass.ae/)                                |
| -Dtx2/mp-rest/url(mandatory)        | -Dtx2/mp-rest/url(mandatory)---Signing Backend URL depending on environment i.e. staging =[<mark style="color:green;">https://stg-apis.uaepass.ae</mark>](https://stg-apis.uaepass.ae/) , production [<mark style="color:green;">https://apis.uaepass.ae</mark>](https://apis.uaepass.ae/) |
| *Dtx.apiKey(mandatory)*             | *Base 64 encoded value of client id and client secret (given by Onboarding team and automatically included) -  To be used as per the environment*                                                                                                                                          |
| *Dtx.signIndenRedirectUrlV2*        | *url to be redirected once the signIdentites and transaction id are generated*                                                                                                                                                                                                             |
| *Dtx.tokenRedirectUrlV2*            | *url to be redirected once the token is generated*                                                                                                                                                                                                                                         |
| Dquarkus.http.port(mandatory)       | as per SP requirement it can be changed                                                                                                                                                                                                                                                    |
| Dmax.allowed.file.size(mandatory)   | Max allowed file size                                                                                                                                                                                                                                                                      |
| Dmax.allowed.files.count(mandatory) | Max allowed file count is 10                                                                                                                                                                                                                                                               |

Please find below snapshot of folder locations below for reference:

#### Folder location where digital-signature.jar file is placed:

![](/files/gNBgRFbonTi79DvMsZAr)

#### Folder location where .jks and .pem files are placed:

![](/files/gNBgRFbonTi79DvMsZAr)


# Hash Signing Process

### The following entails 3 steps:

{% content-ref url="/pages/-MkkTem2vj9U2gkvftpS" %}
[1. Start the Process](/feature-guides/signature-integration-guide/hash-signing/hash-signing-single-document/hash-signing-java-sdk-set-up/hash-signing-process/1.-start-the-process)
{% endcontent-ref %}

{% content-ref url="/pages/-MkkfXBdgGwrBAY6WyKu" %}
[2. Initiate Signing Process](/feature-guides/signature-integration-guide/hash-signing/hash-signing-single-document/hash-signing-java-sdk-set-up/hash-signing-process/3.-initiate-signing-request)
{% endcontent-ref %}

{% content-ref url="/pages/-Mkkj52lVrXzRuSOzVHc" %}
[3. Sign PDF Document](/feature-guides/signature-integration-guide/hash-signing/hash-signing-single-document/hash-signing-java-sdk-set-up/hash-signing-process/5.-sign-pdf-document)
{% endcontent-ref %}


# 1. Start the Process

Once the first Java command is running, entity has to make a call to below API to start the signature process:&#x20;

## API for Signature

<mark style="color:blue;">`GET`</mark> `http://localhost:8089/v2/signature/start`

{% tabs %}
{% tab title="200" %}

```json

{
 https://stg-id.uaepass.ae/trustedx-authserver/oauth/main-as?response_type=code&client_id={client_id}&redirect_uri=http://localhost:8689/uaepass/sign-identity&scope=urn:safelayer:eidas:sign:identity:profile&acr_values=urn:digitalid:authentication:flow:mobile&ui_locales=en&register_group_labelsM=qualified
}
```

{% endtab %}

{% tab title="400" %}
{&#x20;

"error": "Invalid request"

&#x20;}
{% endtab %}
{% endtabs %}

![](/files/eVFXLFmImgeih4mmdCU6)


# 2. Initiate Signing Process

Invoke the above URL (as shown in the screenshot) in browser to obtain the sign identities and transaction id value. The transaction id remains valid for 10 mins.

![](/files/OQi4RxzqsBBXt7yZt5Xq)

## Invoke the API:

The above obtained signing identity and txId needs to be passed in the next API call along with the document.

## Initiate Signing Request

<mark style="color:orange;">`PUT`</mark> `http://localhost:8089/v2/signature/request`

#### Headers

| Name         | Type   | Description          |
| ------------ | ------ | -------------------- |
| Content-Type | string | multipart/form-data; |

{% tabs %}
{% tab title="200 " %}

```
{
https://stg-id.uaepass.ae/trustedx-authserver/oauth/main-as?response_type=code&client_id={client_id}&redirect_uri=http://localhost:8689/uaepass/token&scope=urn:safelayer:eidas:sign:identity:use:server&state=1910298837&digests_summary=bW78y7Ul9ilVfxniWU8ZSeacWzlXjUvq8NY4XHzjrKGRPIYdGShWdaHaHT6K4szy&digests_summary_algorithm=SHA384&sign_identity_id=tec7vgkfc0dmmeu5bvhv9lh394
}
```

{% endtab %}

{% tab title="400" %}
{&#x20;

"error": "Invalid request"&#x20;

}
{% endtab %}
{% endtabs %}

![](/files/T9NEhau7fWJbbFsVNpHW)

**List of attributes for request body:**

| Attributes                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| txId(mandatory)                                | <p>Transaction id for signing request</p><p><strong>Note</strong>: Transaction ID is valid for only 10 minutes and operation should end within the same period.</p>                                                                                                                                                                                                                                                                                                                                 |
| digestAlgorithm(mandatory)                     | <p>Entity can use one of the digest algorithms from below according to their requirement:</p><p>SHA256</p><p>SHA384</p><p>SHA512</p>                                                                                                                                                                                                                                                                                                                                                                |
| signIdentityId(mandatory)                      | User’s qualified certificate id                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| file(mandatory)                                | Pdf file which is to be signed                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| sigRect(optional)                              | <p>Default values: \[36,748,108,32]</p><p>First two values are X and Y co-ordinates, second two values are width and height of the signature dimensions.</p>                                                                                                                                                                                                                                                                                                                                        |
| sigPageNo(optional)                            | <p>Default page: 1</p><p>Page number where signature is to be appeared</p><p>Example: 1</p>                                                                                                                                                                                                                                                                                                                                                                                                         |
| SPCustomerIdRef  – passed as query parameters. | <p>The value of this header should represent unique extended customer identification.</p><p>If Service provider is consuming hash signing API’s for their own organization then this value should be passed as “self”.</p><p>If Service provider is consuming hash signing API’s for other organizations or for selling the application then this value should be passed as “Organization name”.</p><p>Example: Organization name is : Dubai Health Authority : Value should be passed as “DHA”</p> |


# 3. Sign PDF Document

## Obtain Access Token:

1- The url obtained from the above API call needs to be invoked in the browser to obtain the access token.

![](/files/JvLBrcN4Dxv06905nsDw)

2- Pass the access token as a part of header **(X-SIGN-ACCESSTOKEN= Access Token)** with the along with the signing identity and transaction id in the next call as shown below

## This API call will create signing process

<mark style="color:green;">`POST`</mark> `http://localhost:8089/v2/signature/sign`

#### Headers

| Name               | Type   | Description                      |
| ------------------ | ------ | -------------------------------- |
| Content-Type       | string | multipart/form-data;             |
| X-SIGN-ACCESSTOKEN | string | value received from the API call |

{% tabs %}
{% tab title="200" %}

````xml
​```
PK
```‌
````

{% endtab %}

{% tab title="400" %}

```javascript
{
   
  "error": "Invalid request"


}
```

{% endtab %}

{% tab title="412: Precondition Failed If you are trying to sign document with either a txId that is being already used to sign a document or txId is wrong." %}

```javascript
{
    Precondition Failed
}
```

{% endtab %}
{% endtabs %}

![](/files/yUY7exfdXS9QzRI9P4xt)

```
{
  "digestAlgorithm": "SHA256",
  "signIdentityId": "string",
  "txId": "string"
}
```

**List of attributes for request body:**

| Attributes                 | Description                                                                                                                                                         |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| txId(mandatory)            | <p>Transaction id for signing request</p><p><strong>Note</strong>: Transaction ID is valid for only 10 minutes and operation should end within the same period.</p> |
| digestAlgorithm(mandatory) | <p>Entity can use one of the digest algorithms from below according to their requirement:</p><p>SHA256</p><p>SHA384</p><p>SHA512</p>                                |
| signIdentityId(mandatory)  | User’s qualified certificate id                                                                                                                                     |


# Endpoints

{% hint style="info" %} <mark style="color:green;">**Note: Please make sure the external endpoints are accessible from the environment you are using the toolkit.**</mark>
{% endhint %}

**Staging**

| Endpoint                     | Usability                                        | URL                                          |
| ---------------------------- | ------------------------------------------------ | -------------------------------------------- |
| Start the process.           | To initiate the start, process from utility      | `http://localhost:8089/v2/signature/start`   |
| Initiate the Signing request | To initiate the signing process from utility     | `http://localhost:8089/v2/signature/request` |
| Sign PDF document            | To initiate the PDF signing process from utility | `http://localhost:8089/v2/signature/sign`    |
| Time Stamping Authority URL  | Internal Call                                    | `https://app.stg-ca.desc.gov.ae`             |
| Hash Signing Base URL        | Internal Call                                    | `https://stg-id.uaepass.ae`                  |
| Signing Backend URL          | Internal Call                                    | `https://stg-apis.uaepass.ae`                |

**Production**

| Endpoint                     |                                                  | URL                                          |
| ---------------------------- | ------------------------------------------------ | -------------------------------------------- |
| Start the process            | To initiate the start, process from utility      | `http://localhost:8089/v2/signature/start`   |
| Initiate the Signing request | To initiate the signing process from utility     | `http://localhost:8089/v2/signature/request` |
| Sign PDF document            | To initiate the PDF signing process from utility | `http://localhost:8089/v2/signature/sign`    |
| Time Stamping Authority URL  | Internal Call                                    | `https://ca-services.desc.gov.ae/adss/tsa`   |
| Hash Signing Base URL        | Internal Call                                    | `https://id.uaepass.ae`                      |
| Signing Backend URL          | Internal Call                                    | `https://apis.uaepass.ae`                    |


# Postman Collection

{% file src="/files/eeHXxPcoz7CzSmslCUP6" %}
Hash Signing Postman Collection
{% endfile %}


# Utility Files

{% hint style="info" %} <mark style="color:green;">Note :</mark> <mark style="color:green;">Please reach out to the respective Onboarding team for Utility Files.</mark>
{% endhint %}


# Hash Signing (Docker Container Set Up)

UAEPASS offers container-based hash signing feature for single/multiple document signing and next steps of this document share the details and guidelines to prepare and install the Hash Signing Docker Image to create standalone microservice container.


# Quick Setup

## Pre-Requisites

#### &#x20;  **System Requirements:**

* OS 64-bit arch-type (Current images will support only in Linux containers).
* Docker container runtime <mark style="color:green;">(</mark>[*<mark style="color:green;">https://docs.docker.com/engine/install/</mark>*](https://docs.docker.com/engine/install/)*)*

#### &#x20;   **Service requirements (Below are configurable):**

* Minimum memory 512 megabytes.

#### &#x20;  **Business requirements:**

* A user who wants to use this service should have Qualified-level signature. Otherwise, the user will not be able to reach the step of signing a document.
* Document count for one batch operation should be no more than 10.
* Maximum size for a single document should be no more than 10 MB.
* Maximum validity of a signed document is limited to 3 years.

## Running service instructions

Follow the below instruction to run the esign docker image.

1. Download and install Docker Window.
2. Verify the docker running using below steps.

   * Open command/terminal application based on windows, Linux, macOS based system.
   * Run this command to verify if docker installed and started.

   <pre class="language-sh" data-full-width="false"><code class="lang-sh">docker version
   </code></pre>

Below is the screenshot for reference:

<figure><img src="/files/Puy7jJDeH8A9gJSzSQM3" alt=""><figcaption></figcaption></figure>

3. Download the provided zip folder and unzip it. Below is the screenshot for reference:

<figure><img src="/files/TJ84VbWcEs6IkikmMlh2" alt=""><figcaption><p><mark style="color:green;">Sample image and .yaml file</mark></p></figcaption></figure>

{% hint style="info" %} <mark style="color:green;">**For Staging and Production environments, Service provider needs to request for Zip file from UAEPASS Onboarding team**</mark><mark style="color:green;">.</mark> <mark style="color:green;"></mark><mark style="color:green;">**The version of the image will be subjected to change.**</mark>
{% endhint %}

<figure><img src="/files/UineXMoEmIVZxzo8dKRh" alt=""><figcaption><p><mark style="color:green;"><strong>sample docker-compose.yaml file</strong></mark> </p></figcaption></figure>

4. Update the docker-compose.yaml file with required properties and save the file. <mark style="color:green;">The .yaml file will be shared by UAE PASS team.</mark>
5. Update image parameter in the docker compose yaml file. Image will be shared by UAE PASS operations team in case of any changes.

&#x20;   `image: "ddtr.dubai.gov.ae/uaepass/esign:1.1.120"`

6. Load the esign docker image.
7. Open command/terminal window and navigate to the esign image downloaded location. Run below command to load esign docker image. Below is the screenshot for reference:

```sh
docker load < [esign_image].tar.gz
Example:docker load < esign_1.1.40.tar.gz
```

<figure><img src="/files/smrO7CAkguFzhBHgZlCR" alt=""><figcaption></figcaption></figure>

{% hint style="info" %} <mark style="color:green;">**Note: Docker compose file and esign image should be in the same folder/location on the local machine.**</mark>
{% endhint %}

8. Navigate to the location of esign and docker compose file and run the below command in step 9.
9. Use below command to run docker image with attached log mode. Below is the screenshot for reference:

```sh
docker-compose [DOCKER_COMPOSE_FILE] up 
Example: docker-compose up
```

<figure><img src="/files/uSsSjKKruZaBxZv2iibY" alt=""><figcaption></figcaption></figure>

10. Use below command to run docker image with detached log mode.

```sh
docker-compose -d  < [DOCKER_COMPOSE_FILE] up
Example: docker-compose up -d
```

<figure><img src="/files/ICnWEUvuTu0MpvXsRlXA" alt=""><figcaption></figcaption></figure>

11. Run below command to stop docker esign service.

```sh
docker-compose down
```


# Hash Signing Process

Hash Signing process includes 3 main steps as below.

{% content-ref url="/pages/mg8aBnwW3DdWlWQhOvi0" %}
[1. Start Signing Process](/feature-guides/signature-integration-guide/hash-signing/bulk-hash-signing-multiple-documents/hash-signing-process/1.-start-signing-process)
{% endcontent-ref %}

{% content-ref url="/pages/ydyI8j6YTmjCJgNvdxJl" %}
[2. Initiate Signing Process](/feature-guides/signature-integration-guide/hash-signing/bulk-hash-signing-multiple-documents/hash-signing-process/2.-initiate-signing-process)
{% endcontent-ref %}

{% content-ref url="/pages/OTXOZ5LKI8CUAYLJGD8V" %}
[3. Sign PDF Document](/feature-guides/signature-integration-guide/hash-signing/bulk-hash-signing-multiple-documents/hash-signing-process/3.-sign-pdf-document)
{% endcontent-ref %}


# 1. Start Signing Process

&#x20;1\.  Once the quick set up is completed, invoke the below API.

<mark style="color:green;">**`GET`**</mark>**` `**<mark style="color:blue;">**`http://localhost:8080/v2/signature/start`**</mark>

**Headers**

| Name         | Value               |
| ------------ | ------------------- |
| Content-Type | multipart/form-data |

**Body**

| Name   | Type | Description |
| ------ | ---- | ----------- |
| `null` | null | null        |

**Response**

{% tabs %}
{% tab title="200" %}
{% code overflow="wrap" %}

```url
{
"
https://stg-id.uaepass.ae/trustedx-authserver/oauth/hsign-as?response_type=code&client_id=sandbox_stage&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fv2%2Fsignature%2Fsign-identity%3FcertType%3Dqualified&scope=urn:safelayer:eidas:sign:identity:use:server urn:uae:digitalid:backend_api:hash_signing&acr_values= &ui_locales=en&register_group_labelsM=qualified
"
}
```

{% endcode %}
{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

<figure><img src="/files/sdvOYverlqE5IvJFcVKy" alt=""><figcaption><p><mark style="color:green;">Sample postman API request and response</mark></p></figcaption></figure>

#### Sample Curl Command

```
curl --location 'http://localhost:8080/v2/signature/start' \
--header 'Content-Type: multipart/form-data'
```

2. Invoke the URL obtained from the API response (as shown in the screenshot) in browser to obtain the sign identities and transaction id value. During this step users will be prompted to authorize and if the Application redirect URL has been configured the txId and signing Identity values will be returned as response header params. Otherwise in response body.

<figure><img src="/files/M7Vfmg6mZcxk57eRxxxV" alt=""><figcaption><p> <mark style="color:green;">User authorization sample</mark></p></figcaption></figure>

<figure><img src="/files/n5pDFQkb0Hv7vv7gkUMm" alt=""><figcaption><p><mark style="color:green;">Sample response when application redirect URL is configured.</mark></p></figcaption></figure>

<figure><img src="/files/pFyiMTqYjWROo6VoQ2J6" alt=""><figcaption><p><mark style="color:green;">Sample response if application redirect URL is not configured</mark></p></figcaption></figure>

{% hint style="info" %} <mark style="color:green;">**The transaction id remains valid for 10 mins.**</mark>
{% endhint %}


# 2. Initiate Signing Process

&#x20;The obtained signing identity and txId during the previous step needs to be passed in the next API call along with the single or multiple documents to be signed.

<mark style="color:blue;">**`PUT http://localhost:8080/v2/signature/request`**</mark>

**Headers**

| Name         | Value               |
| ------------ | ------------------- |
| Content-Type | multipart/form-data |

**Body**

| Name            | Description                                                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| digestAlgorithm | SHA256                                                                                                                                                  |
| signIdentityId  | ckqtokgre4o5mrk4bajtk413ui                                                                                                                              |
| txId            | 90ca005cfb4d4827b1247889166b72fe                                                                                                                        |
| file            | file1.pdf file2.pdf                                                                                                                                     |
| sigProp         | { "signPropDetail": \[ { "fileName": "file1.pdf", "signInfo": "1:50, 50, 200,200]" }, { "fileName": "file2.pdf", "signInfo": "1:\[50,50,200,200]" } ] } |

**Response**

{% tabs %}
{% tab title="200" %}
{% code overflow="wrap" %}

````url
{
  ```
https://stg-id.uaepass.ae/trustedx-authserver/oauth/hsign-as?response_type=code&client_id=sandbox_stage&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fv2%2Fsignature%2Ftoken&scope=urn:uae:digitalid:backend_api:hash_signing urn:safelayer:eidas:sign:identity:use:server&state=1434459749&digests_summary=npBScEri0PAqJ8yWz11jvcjFOlzVkDijlM-osjrX98k%3D&digests_summary_algorithm=SHA256&sign_identity_id=ckqtokgre4o5mrk4bajtk413ui
```
}
````

{% endcode %}
{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

Provide the below values for “signProp” parameter in the API call. The values should be adjusted accordingly as per the files.

```
{
  "signPropDetail": [
    {
      "fileName": "sample1.pdf",
      "signInfo": "1:[50, 600, 200, 100]"
    },
    {
      "fileName": "sample2.pdf",
      "signInfo": "1:[50, 600, 200, 100]"
    }
  ]
}

```

**Description of parameters in the above request body:**

| filename | The name of the file that needs to be signed. It should be exactly same as the selected one.                                                                                                                              |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| signInfo | Page number and the signing position on the specified page. The first 2 values (50,600) specify the values for lower left corner X,Y coordinates and other two 200,100) represent the upper right corner X,Y coordinates. |

| txId(mandatory)            | <p>Transaction id for signing request.</p><p><strong>Note</strong>: Transaction ID is valid for only 10 minutes and operation should end within the same period.</p> |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| digestAlgorithm(mandatory) | <p>Entity can use one of the digest algorithms from below according to their requirement:</p><p>SHA256</p><p>SHA384</p><p>SHA512</p>                                 |
| signIdentityId(mandatory)  | User’s qualified certificate id                                                                                                                                      |
| file(mandatory)            | Pdf file which is to be signed                                                                                                                                       |
| signProp                   | As described above                                                                                                                                                   |

<figure><img src="/files/TGkuMudPdQmGnn1vgFkB" alt=""><figcaption><p><mark style="color:green;">Sample postman request</mark></p></figcaption></figure>

#### Sample Curl Command

```url
curl --location --request PUT 'http://localhost:8080/v2/signature/request' \
--header 'Content-Type: multipart/form-data' \
--form 'digestAlgorithm="SHA256"' \
--form 'signIdentityId="49o09dt4v47lvd2r14tesod0at"' \
--form 'txId="4f1068dbe3f64aefa45ada9555c9ba0b"' \
--form 'file=@"/C:path to file/file1.pdf"' \
--form 'file=@"/C:path to file/file2.pdf"' \
--form 'sigProp="{
  \"signPropDetail\": [
    {
      \"fileName\": \"file1.pdf\",
      \"signInfo\": \"1:50, 50, 200,200]\"

    },
    {
      \"fileName\": \"file2.pdf\",
      \"signInfo\": \"1:[50,50,200,200]\"
    }
  ]
}"'
```


# 3. Sign PDF Document

**Step 1. Obtain Access Token:**

The response URL obtained from the previous API call needs to be invoked in the browser to obtain the access token. The user needs to enter the qualified signing password during this step to obtain the access token.

<figure><img src="/files/hxgvb45y6HbobdACMHmJ" alt=""><figcaption><p><mark style="color:green;">Sample response for obtaining access token</mark></p></figcaption></figure>

**Step 2. Invoking signing API**

<mark style="color:orange;">**`POST`**</mark> <mark style="color:orange;">**`http://localhost:8080/v2/signature/sign`**</mark>

Signing  API

#### Headers

| Name               | Value                                                            |
| ------------------ | ---------------------------------------------------------------- |
| Content-Type       | multipart/form-data                                              |
| X-SIGN-ACCESSTOKEN | 89777718e027d33dd23f8e4f560128c6cc632336870b58fd8daed86c0727a76a |

#### Body

| Name            | Value                            |
| --------------- | -------------------------------- |
| digestAlgorithm | SHA256                           |
| signIdentityId  | ckqtokgre4o5mrk4bajtk413ui       |
| txId            | 90ca005cfb4d4827b1247889166b72fe |

{% tabs %}
{% tab title="200: OK " %}
"<mark style="color:blue;">PK - Signed files in .zip format</mark>"
{% endtab %}

{% tab title="400: Bad Request " %}
" <mark style="color:blue;">Invalid request</mark>"
{% endtab %}
{% endtabs %}

Pass the access token as a part of header (X-SIGN-ACCESSTOKEN= Access Token) along with the signing identity and transaction id in the next API call as shown below.

<figure><img src="/files/ZKefY8b1XvnElYaqAqdR" alt=""><figcaption><p><mark style="color:green;">Sample postman request</mark></p></figcaption></figure>

**Sample Curl Command**

```
curl --location 'http://localhost:8080/v2/signature/sign' \
--header 'Content-Type: multipart/form-data' \
--header 'X-SIGN-ACCESSTOKEN: 89777718e027d33dd23f8e4f560128c6cc632336870b58fd8daed86c0727a76a' \
--form 'digestAlgorithm="SHA256"' \
--form 'signIdentityId="ckqtoskgre4o5mrk4bajtsk41r3ui"' \
--form 'txId="90ca005cfb4d4827b1247889166b72fe"'
```

**List of attributes for request body:**

| txId            | <p>Transaction id for signing request.</p><p><strong>Note</strong>: Transaction ID is valid for only 10 minutes and operation should end within the same period.</p> |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| digestAlgorithm | <p>Entity can use one of the digest algorithms from below according to their requirement:</p><p>SHA256</p><p>SHA384</p><p>SHA512</p>                                 |
| signIdentityId  | User’s qualified certificate id                                                                                                                                      |


# Endpoints

{% hint style="info" %} <mark style="color:green;">**Please make sure the external endpoints are accessible from the environment you are running the docket image.**</mark>
{% endhint %}

**Staging Environment**

| Endpoint                      | Usability                                        | URL                                          |
| ----------------------------- | ------------------------------------------------ | -------------------------------------------- |
| Start the process.            | To initiate the start, process from utility      | `http://localhost:8080/v2/signature/start`   |
| Initiate the Signing request. | To initiate the signing process from utility     | `http://localhost:8080/v2/signature/request` |
| Sign PDF document             | To initiate the PDF signing process from utility | `http://localhost:8080/v2/signature/sign`    |
| Hash Signing Base URL         | Internal Call                                    | `https://stg-id.uaepass.ae`                  |
| Signing Backend URL           | Internal Call                                    | `https://stg-apis.uaepass.ae`                |

#### Production Environment

| Endpoint                      | Usability                                        | URL                                          |
| ----------------------------- | ------------------------------------------------ | -------------------------------------------- |
| Start the process.            | To initiate the start, process from utility      | `http://localhost:8080/v2/signature/start`   |
| Initiate the Signing request. | To initiate the signing process from utility     | `http://localhost:8080/v2/signature/request` |
| Sign PDF document             | To initiate the PDF signing process from utility | `http://localhost:8080/v2/signature/sign`    |
| Hash Signing Base URL         | Internal Call                                    | `https://id.uaepass.ae`                      |
| Signing Backend URL           | Internal Call                                    | `https://apis.uaepass.ae`                    |


# Postman Collection

The below folder will contain

1. Postman Collection for docker based bulk hash signing
2. Sample Files

for testing purposes.

{% file src="/files/W3SvJRcsIaJEYtT842yB" %}


# Bulk Hash Signing (Multiple Documents)

UAEPASS container-based hash signing feature can be used for multiple documents signing.

&#x20;Next steps of this document share the details and guidelines to prepare and install the Multiple PDF Documents Digital Hash Signing Docker Image to create standalone microservice container.

{% hint style="info" %} <mark style="color:green;">**Note: This approach will support both single document signing and multiple documents signing.**</mark>&#x20;
{% endhint %}




---

[Next Page](/llms-full.txt/1)