> For the complete documentation index, see [llms.txt](https://docs.fill-easy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fill-easy.com/uae-pass.md).

# UAE Pass

UAE Pass is the UAE's national digital identity solution, providing secure and seamless access to government and private sector services. It simplifies authentication with a single digital identity, reducing complexity and enhancing security.

This guide explains how to integrate with the UAE Pass API, including endpoints, authentication, error handling, and best practices.

***

#### Key Features

* **Unified Identity**: Access multiple services with one secure login.
* **Enhanced Security**: Advanced encryption and multi-factor authentication.
* **Easy Integration**: Streamlined APIs for quick deployment.
* **Future-Ready**: Supports the UAE’s smart digital economy vision.

***

#### Services

1. **Authentication**: Verify user identity.
2. **Digital Signing**: Enable legally valid digital document signing.

***

#### Usage Flow

1. Choose a service
2. Send a corresponding request in the ***Request Data*** folder
3. Send follow up request(s)\* to ***Polling/Poll Data***

***

Integrate UAE Pass to deliver secure and efficient digital experiences.

## Authentication

> Retrieves user identity details following a successful UAE Pass login.

```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"UAE Pass","description":"UAE Pass is the UAE's national digital identity solution, providing secure\nand seamless access to government and private sector services. It\nsimplifies authentication with a single digital identity, reducing\ncomplexity and enhancing security.\n\n\nThis guide explains how to integrate with the UAE Pass API, including\nendpoints, authentication, error handling, and best practices.\n\n\n---\n\n\n### Key Features\n\n\n- **Unified Identity**: Access multiple services with one secure login.\n    \n- **Enhanced Security**: Advanced encryption and multi-factor\nauthentication.\n    \n- **Easy Integration**: Streamlined APIs for quick deployment.\n    \n- **Future-Ready**: Supports the UAE’s smart digital economy vision.\n    \n\n---\n\n\n### Services\n\n\n1. **Authentication**: Verify user identity.\n    \n2. **Digital Signing**: Enable legally valid digital document signing.\n    \n\n---\n\n\n### Usage Flow\n\n\n1. Choose a service\n    \n2. Send a corresponding request in the _**Request Data**_ folder\n    \n3. Send follow up request(s)\\* to _**Polling/Poll Data**_\n    \n\n---\n\n\nIntegrate UAE Pass to deliver secure and efficient digital experiences.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}},"schemas":{"RedirectUri":{"type":"string","description":"Redirect URI after user authorization.\n\nBrowser: HTTPS URL to your website.\n\niOS: HTTPS Universal link\n\nAndroid: Package name (com.filleasy.app)\n"},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/uaepass/request/auth":{"post":{"tags":["UAE Pass"],"summary":"Authentication","description":"Retrieves user identity details following a successful UAE Pass login.","operationId":"uaepassAuth","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["redirect","source"],"properties":{"redirect":{"$ref":"#/components/schemas/RedirectUri"},"scope":{"type":"string","description":"List of values, separated by spaces, that represent the scope of the authorization that the application wants to obtain.\nIt queries the scopes required for accessing the resources or services in question.\nAvailable scopes: sub, fullnameAR, gender, mobile, lastnameEN, fullnameEN, uuid, lastnameAR, idn, nationalityEN, firstnameEN, userType, nationalityAR, firstnameAR, email.\n(To be shared by UAEPASS Team if its value is other than specified in sample above)\nInclude urn:uae:digitalid:digitalvault:datasharerequest when the login will be\nfollowed by a Digital Vault presentation request (/uaepass/request/presentation);\nuserType is added to that login automatically so the account level is known.\n"},"lang":{"type":"string","enum":["en","ar"],"description":"UAE Pass display language, case sensitive"},"source":{"type":"string","enum":["PC_Browser","android","iOS","Mobile_Browser"],"description":"Platform source for the authentication request"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["token","oAuthUrl"],"properties":{"token":{"type":"string","description":"JWT token for polling authentication status"},"oAuthUrl":{"type":"string","format":"uri","description":"UAE Pass authorization URL to redirect user to"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Poll Data

> Short poll this endpoint, passing in the \`token\` (from endpoints in \`Request Data\` folder) to obtain the results.\
> \
> For authentication, this includes user data. For signing, this provides a link by which the signed document can be obtained.\
> \
> For document presentations, each returned document carries its data attributes (\`claim\`) and,\
> when the issuer includes a PDF rendering, a \`visualizationUrl\` — a download link valid for one hour.\
> Card images embedded in the claim are not returned; use the PDF rendering for a visual copy.\
> \
> A login the citizen cancelled, or a presentation they rejected, returns \`299\`; a presentation\
> that failed signature verification returns \`400\`. All carry the reason in \`error\`.\
> \
> The response's \`token\` is a JWT or JWE depending if there's sensitive personal data. You should handle them like so:\
> \
> \- \`JWT\` verify\\\* token\
>     \
> \- \`JWE\` decrypt using the private keys that Fill Easy has previously provided.\
>     \
> \
> Please note that the data result is returned only once and is deleted immediately.\
> \
> \\\*you can try using online decoder like \[<https://jwt.io/]\\(https://jwt.io/)\\>
> \
> all responses are \`JWE\` unless noted otherwise.

```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"UAE Pass","description":"UAE Pass is the UAE's national digital identity solution, providing secure\nand seamless access to government and private sector services. It\nsimplifies authentication with a single digital identity, reducing\ncomplexity and enhancing security.\n\n\nThis guide explains how to integrate with the UAE Pass API, including\nendpoints, authentication, error handling, and best practices.\n\n\n---\n\n\n### Key Features\n\n\n- **Unified Identity**: Access multiple services with one secure login.\n    \n- **Enhanced Security**: Advanced encryption and multi-factor\nauthentication.\n    \n- **Easy Integration**: Streamlined APIs for quick deployment.\n    \n- **Future-Ready**: Supports the UAE’s smart digital economy vision.\n    \n\n---\n\n\n### Services\n\n\n1. **Authentication**: Verify user identity.\n    \n2. **Digital Signing**: Enable legally valid digital document signing.\n    \n\n---\n\n\n### Usage Flow\n\n\n1. Choose a service\n    \n2. Send a corresponding request in the _**Request Data**_ folder\n    \n3. Send follow up request(s)\\* to _**Polling/Poll Data**_\n    \n\n---\n\n\nIntegrate UAE Pass to deliver secure and efficient digital experiences.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}},"schemas":{"Token":{"type":"string","pattern":"^[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]*$","description":"JWT token"}}},"paths":{"/uaepass/poll":{"post":{"tags":["UAE Pass"],"summary":"Poll Data","description":"Short poll this endpoint, passing in the `token` (from endpoints in `Request Data` folder) to obtain the results.\n\nFor authentication, this includes user data. For signing, this provides a link by which the signed document can be obtained.\n\nFor document presentations, each returned document carries its data attributes (`claim`) and,\nwhen the issuer includes a PDF rendering, a `visualizationUrl` — a download link valid for one hour.\nCard images embedded in the claim are not returned; use the PDF rendering for a visual copy.\n\nA login the citizen cancelled, or a presentation they rejected, returns `299`; a presentation\nthat failed signature verification returns `400`. All carry the reason in `error`.\n\nThe response's `token` is a JWT or JWE depending if there's sensitive personal data. You should handle them like so:\n\n- `JWT` verify\\* token\n    \n- `JWE` decrypt using the private keys that Fill Easy has previously provided.\n    \n\nPlease note that the data result is returned only once and is deleted immediately.\n\n\\*you can try using online decoder like [https://jwt.io/](https://jwt.io/)\n\nall responses are `JWE` unless noted otherwise.","operationId":"uaepassPoll","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"$ref":"#/components/schemas/Token"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"data":{"description":"Response data from UAE Pass"}}}}}},"202":{"description":"Pending - Authentication not yet complete","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"299":{"description":"The citizen rejected the request in the UAE PASS app, or cancelled the login","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string","enum":["USER_REJECTED","USER_CANCELLED"]}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string","description":"Why the request failed, e.g. `INVALID_SIGNATURE` for a presentation that did not verify."}}}}}},"410":{"description":"The request expired before the citizen acted on it"}}}}}}
```

## Callback

> UAE Pass will redirect to this endpoint after user authorization.\
> This endpoint then redirects the user to the original \`redirect\` URI provided in the\
> \`/uaepass/request/auth\` request. A login the user cancelled at UAE PASS is redirected there\
> with \`?error=uaepass\_cancelled\`, a failed token exchange with \`?error=uaepass\_auth\_failed\`;\
> \`/uaepass/poll\` reports the outcome either way.

```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"UAE Pass","description":"UAE Pass is the UAE's national digital identity solution, providing secure\nand seamless access to government and private sector services. It\nsimplifies authentication with a single digital identity, reducing\ncomplexity and enhancing security.\n\n\nThis guide explains how to integrate with the UAE Pass API, including\nendpoints, authentication, error handling, and best practices.\n\n\n---\n\n\n### Key Features\n\n\n- **Unified Identity**: Access multiple services with one secure login.\n    \n- **Enhanced Security**: Advanced encryption and multi-factor\nauthentication.\n    \n- **Easy Integration**: Streamlined APIs for quick deployment.\n    \n- **Future-Ready**: Supports the UAE’s smart digital economy vision.\n    \n\n---\n\n\n### Services\n\n\n1. **Authentication**: Verify user identity.\n    \n2. **Digital Signing**: Enable legally valid digital document signing.\n    \n\n---\n\n\n### Usage Flow\n\n\n1. Choose a service\n    \n2. Send a corresponding request in the _**Request Data**_ folder\n    \n3. Send follow up request(s)\\* to _**Polling/Poll Data**_\n    \n\n---\n\n\nIntegrate UAE Pass to deliver secure and efficient digital experiences.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[],"paths":{"/uaepass/callback":{"get":{"tags":["UAE Pass"],"description":"UAE Pass will redirect to this endpoint after user authorization.\nThis endpoint then redirects the user to the original `redirect` URI provided in the\n`/uaepass/request/auth` request. A login the user cancelled at UAE PASS is redirected there\nwith `?error=uaepass_cancelled`, a failed token exchange with `?error=uaepass_auth_failed`;\n`/uaepass/poll` reports the outcome either way.","summary":"Callback","operationId":"uaepassCallback","responses":{"302":{"description":"Redirect to client application"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```

## POST /uaepass/logout

> UAEPass Logout

```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"UAE Pass","description":"UAE Pass is the UAE's national digital identity solution, providing secure\nand seamless access to government and private sector services. It\nsimplifies authentication with a single digital identity, reducing\ncomplexity and enhancing security.\n\n\nThis guide explains how to integrate with the UAE Pass API, including\nendpoints, authentication, error handling, and best practices.\n\n\n---\n\n\n### Key Features\n\n\n- **Unified Identity**: Access multiple services with one secure login.\n    \n- **Enhanced Security**: Advanced encryption and multi-factor\nauthentication.\n    \n- **Easy Integration**: Streamlined APIs for quick deployment.\n    \n- **Future-Ready**: Supports the UAE’s smart digital economy vision.\n    \n\n---\n\n\n### Services\n\n\n1. **Authentication**: Verify user identity.\n    \n2. **Digital Signing**: Enable legally valid digital document signing.\n    \n\n---\n\n\n### Usage Flow\n\n\n1. Choose a service\n    \n2. Send a corresponding request in the _**Request Data**_ folder\n    \n3. Send follow up request(s)\\* to _**Polling/Poll Data**_\n    \n\n---\n\n\nIntegrate UAE Pass to deliver secure and efficient digital experiences.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}},"schemas":{"RedirectUri":{"type":"string","description":"Redirect URI after user authorization.\n\nBrowser: HTTPS URL to your website.\n\niOS: HTTPS Universal link\n\nAndroid: Package name (com.filleasy.app)\n"},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/uaepass/logout":{"post":{"tags":["UAE Pass"],"summary":"UAEPass Logout","operationId":"uaepassLogout","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["redirect"],"properties":{"redirect":{"$ref":"#/components/schemas/RedirectUri"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["logoutUrl"],"properties":{"logoutUrl":{"type":"string","format":"uri","description":"UAE Pass logout URL to redirect user to"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Request Document Presentation

> Ask a citizen to share documents from their UAE Pass Digital Vault.\
> \
> The citizen must first complete a UAE Pass login started with \`/uaepass/request/auth\`,\
> requesting the \`urn:uae:digitalid:digitalvault:datasharerequest\` scope — Digital Vault\
> identifies whose app to notify from that session's access token. Pass that call's \`token\`\
> as \`authToken\`; it stops working when the login session expires (about an hour), after\
> which a new login is required. Only verified (SOP3) accounts can share documents; a lower\
> level is refused with \`403\` before any notification is raised. The session's access token is\
> checked with UAE PASS's token validation API first; one UAE PASS reports as no longer active\
> is refused with \`400\` (\`error: SESSION\_INACTIVE\`) and a new login is required.\
> \
> A notification is raised in the citizen's UAE Pass app listing the requested documents.\
> Once they approve it with their UAE Pass PIN, Digital Vault pushes the signed documents to\
> Fill Easy and the result becomes available from \`/uaepass/poll\` using the returned \`token\`.\
> \
> Approval happens in the citizen's UAE Pass app, independently of their session on your\
> channel. Store the returned \`token\` against your customer record so you can collect the\
> documents whenever they return.

```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"UAE Pass","description":"UAE Pass is the UAE's national digital identity solution, providing secure\nand seamless access to government and private sector services. It\nsimplifies authentication with a single digital identity, reducing\ncomplexity and enhancing security.\n\n\nThis guide explains how to integrate with the UAE Pass API, including\nendpoints, authentication, error handling, and best practices.\n\n\n---\n\n\n### Key Features\n\n\n- **Unified Identity**: Access multiple services with one secure login.\n    \n- **Enhanced Security**: Advanced encryption and multi-factor\nauthentication.\n    \n- **Easy Integration**: Streamlined APIs for quick deployment.\n    \n- **Future-Ready**: Supports the UAE’s smart digital economy vision.\n    \n\n---\n\n\n### Services\n\n\n1. **Authentication**: Verify user identity.\n    \n2. **Digital Signing**: Enable legally valid digital document signing.\n    \n\n---\n\n\n### Usage Flow\n\n\n1. Choose a service\n    \n2. Send a corresponding request in the _**Request Data**_ folder\n    \n3. Send follow up request(s)\\* to _**Polling/Poll Data**_\n    \n\n---\n\n\nIntegrate UAE Pass to deliver secure and efficient digital experiences.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}},"schemas":{"Token":{"type":"string","pattern":"^[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]*$","description":"JWT token"},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized - Token is missing, invalid, or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/uaepass/request/presentation":{"post":{"tags":["UAE Pass"],"summary":"Request Document Presentation","description":"Ask a citizen to share documents from their UAE Pass Digital Vault.\n\nThe citizen must first complete a UAE Pass login started with `/uaepass/request/auth`,\nrequesting the `urn:uae:digitalid:digitalvault:datasharerequest` scope — Digital Vault\nidentifies whose app to notify from that session's access token. Pass that call's `token`\nas `authToken`; it stops working when the login session expires (about an hour), after\nwhich a new login is required. Only verified (SOP3) accounts can share documents; a lower\nlevel is refused with `403` before any notification is raised. The session's access token is\nchecked with UAE PASS's token validation API first; one UAE PASS reports as no longer active\nis refused with `400` (`error: SESSION_INACTIVE`) and a new login is required.\n\nA notification is raised in the citizen's UAE Pass app listing the requested documents.\nOnce they approve it with their UAE Pass PIN, Digital Vault pushes the signed documents to\nFill Easy and the result becomes available from `/uaepass/poll` using the returned `token`.\n\nApproval happens in the citizen's UAE Pass app, independently of their session on your\nchannel. Store the returned `token` against your customer record so you can collect the\ndocuments whenever they return.","operationId":"uaepassRequestPresentation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["purpose","purposeAr","authToken","documents"],"properties":{"purpose":{"type":"string","description":"Reason shown to the citizen in the UAE Pass app, in English."},"purposeAr":{"type":"string","description":"Reason shown to the citizen in the UAE Pass app, in Arabic."},"authToken":{"$ref":"#/components/schemas/Token"},"subjectId":{"type":"string","description":"Your own stable identifier for this citizen. When supplied, a repeat request made\nwhile an earlier one is still open — or already approved but not yet collected from\n`/uaepass/poll` — returns that request instead of raising a second notification in\nthe citizen's UAE Pass app."},"origin":{"type":"string","enum":["WEB","MOBILE"],"default":"WEB","description":"Where the journey started. Use `WEB` when the UAE Pass app is not on the\nsame device as your channel, so Digital Vault raises a push notification."},"expiryMinutes":{"type":"integer","minimum":5,"default":60,"description":"How long the citizen has to act on the notification."},"verifiedAttributes":{"type":"array","description":"UAE Pass verified attributes to request alongside the documents.","items":{"type":"string"}},"documents":{"type":"array","minItems":1,"items":{"type":"object","required":["type","required"],"properties":{"type":{"type":"string","description":"Digital Vault document mnemonic."},"required":{"type":"boolean","description":"Whether the citizen must share this document to proceed."},"selfSignedAccepted":{"type":"boolean","description":"Whether a citizen-uploaded copy is acceptable for this document."}}}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["token","requestId"],"properties":{"token":{"$ref":"#/components/schemas/Token"},"requestId":{"type":"string","description":"Fill Easy reference for this request, echoed in support tickets."},"reused":{"type":"boolean","description":"True when an earlier request for this `subjectId` has been returned instead of\nraising a new notification. Poll the token: a pending result means the notification\nis still waiting in the citizen's UAE Pass app, a success result means they have\nalready shared and you can continue the journey."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The UAE PASS account is below SOP3 and cannot share documents","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string","enum":["NOT_SOP3"]},"userType":{"type":"string"}}}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```