# API Security

### <mark style="color:green;">API Authentication – SP to UAEPASS</mark>&#x20;

UAEPASS APIs are secured with a client credential token. To obtain this token, API consumers must be onboarded as a service provider by the UAEPASS operations team. Upon onboarding, they receive a client ID and client secret, which are used to generate the token as per the specified process.

#### <mark style="color:orange;">Generating client credential tokens</mark>

| API URL     | [https://stg-ids.uaepass.ae/oauth2/token  ](https://stg-ids.uaepass.ae/oauth2/token)                                                                                                                                                                                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Source      | Service Provider (Data owner)                                                                                                                                                                                                                                                                                                                                                          |
| Target      | UAEPASS                                                                                                                                                                                                                                                                                                                                                                                |
| Sample cURL | <p>curl --location '<https://stg-ids.uaepass.ae/oauth2/token>' \ </p><p>--header 'Authorization: Basic \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*' \ </p><p>--header 'Content-Type: application/x-www-form-urlencoded' \ </p><p>--data-urlencode 'scope=urn:uae:digitalid:backend\_api:manage\_user\_consent openid ' \ </p><p>--data-urlencode 'grant\_type=client\_credentials' </p> |
| Method      | POST                                                                                                                                                                                                                                                                                                                                                                                   |
| Security    | (CCG) Client Credentails Grant                                                                                                                                                                                                                                                                                                                                                         |
| Headers     | <p>Authorization: {Basic with client credentials} – base64(clientid:client\_secret) – to be obtained from UAEPASS operations team. </p><p>Content-Type:  {Standard form url encoded type for token} </p>                                                                                                                                                                               |

#### Request Payload

```
curl --location 'https://stg-ids.uaepass.ae/oauth2/token' \ 
--header 'Authorization: Basic *********************' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \ 
--data-urlencode 'scope=urn:uae:digitalid:backend_api:manage_user_consent openid ' \ 
--data-urlencode 'grant_type=client_credentials' 
```

#### Response Payload

| Sample success response | <p>{ </p><p>    "access\_token": "4d6861ed-aa8d-31e3-acff-df3413ee68bf", </p><p>    "scope": "openid urn:uae:digitalid:backend\_api:manage\_user\_consent", </p><p>    "id\_token": "eyJ4NXQiOi…” </p><p>    "token\_type": "Bearer", </p><p>    "expires\_in": 3600 </p><p>} </p> |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Values of X-UP-AccessToken & Authorization headers&#x20;

The value of access\_token from the above response should be used for the header ‘X-UP-AccessToken’.&#x20;

Similarly, the value of id\_token should be used to populate the value of the header ‘Authorization’.

### <mark style="color:green;">API Authentication – UAEPASS to SP</mark>&#x20;

Callback API invoked by UAEPASS to notify SP about a consent decision made by user is protected by API Key. A value for this API key must be agreed upon and shared with UAEPASS via secured channel.&#x20;

This will be populated in the value of the header X-API-Key&#x20;

{% hint style="info" %} <mark style="color:green;">In addition to the X-API-KEY, we can also send an authorization header with basic credentials, depending on the service provider’s configuration in UAEPASS and it is optional based on service requirement.</mark>&#x20;
{% endhint %}

#### <mark style="color:orange;">API nonrepudiation – HMAC</mark>&#x20;

To guarantee that request body of the API(s) have not been modified inflight, and that the origin of the API invocations is legitimate. HMAC (HmacSHA256) has been used.&#x20;

Fields included in creating the HMAC tokens.&#x20;

1. API request body &#x20;
2. Value of Request header: X-Timestamp&#x20;

Raw input to HMAC to generate HMAC token -> header\[X-Timestamp] + request body json.

{% hint style="info" %}
&#x20;<mark style="color:green;">Kindly note that both SP & UAEPASS must agree on the above implementation to make HMAC verification possible on both ends. Once HMAC tokens are generated, they should be added as the value of the header ‘X-UAEPASS-Signature’.</mark>
{% endhint %}