# Authentication request

Before sending its request, the **APP** must create an "authentication request data" object (`auth_req_data`) it will send to the **PKSA**

### auth\_req\_data

```javascript
{
    app: {
        name: string
        description: string = undefined
        icon: string = undefined
    },
    challenge: object = undefined
    token: string = undefined // DEPRECATED - protocol < 1 only
}
```

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

* **`app`**: an object describing the application
  * **`name`**: short name of the app (ex: "myapp")
  * **`description`**: *(optional)* description of the app (ex: "My Hive Application")
  * **`icon`**: *(optional)* URL to retrieve the application icon (ex: "<https://myapp.com/logo.png>")
* **`challenge`**: *(optional)* a `challenge_data` object that the app can pass to the PKSA for signing (see [Challenge request](/developer-documentation/has-for-applications/challenge/challenge-request.md))<br>
* **`token`**: *(optional)* a valid session token previously received from the **PKSA -&#x20;*****Deprecated since protocol V1***
  {% endtab %}
  {% endtabs %}

{% hint style="info" %}
Sending a challenge to the **PKSA** with an auth\_req enables the **APP** to perform both an authentication and a challenge signing in one round trip.
{% endhint %}

The **APP** must then encrypt the `auth_req_data` object using the `auth_key` (see [Encryption Key](/developer-documentation/has-for-applications/encryption-key-auth_key.md))

Finally, the **APP** sends its authentication request (`auth_req`) to the **HAS** using the following message:

### auth\_req

```javascript
{ 
    cmd: "auth_req"
    account: string
    data: string
}
```

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

* **`account`**: the Hive account name that the application wants to authenticate
* **`data`**: the Base64 representation of an encrypted `auth_req_data` object
  {% endtab %}
  {% endtabs %}

{% hint style="info" %}
Providing an existing `token` with the `auth_req` simplifies the authentication process. Indeed, if a **PKSA** stores the token and confirms its validity, it is no longer required to scan a QR code because the **PKSA** already has the associated `auth_key`.
{% endhint %}

{% hint style="info" %}
When using a **PKSA** running in [Service Mode](/tutorials/pksa-code-example/service-mode.md), the **APP** must add the `auth_key` property to the `auh_req` it sends to the **HAS** server.

The `auth_key` must be encrypted with the encryption secret (auth\_req\_secret) it shares with the **PKSA** service.

example:&#x20;

`{` \
&#x20;  `cmd: "auth_req",` \
&#x20;  `account: "username",` \
&#x20;  `data:`` `*`{{encrypted_data_base64}}`*`,`\
&#x20;  `auth_key: CryptoJS.Encrypt(auth_key, auth_req_secret)` \
`}`
{% endhint %}

The **HAS** will reply with an auth\_wait message

### auth\_wait

```javascript
{
    cmd: "auth_wait"
    uuid: string
    expire: number
    account: string
}
```

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

* **`uuid`**: a unique identifier given by the **HAS** to the request
* **`expire`**: UNIX timestamp when the authentication request will expire
* **`account`**: account doing the authentication request
  {% endtab %}
  {% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hiveauth.com/developer-documentation/has-for-applications/authentication/authentication-request.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.