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

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

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)

• token: (optional) a valid session token previously received from the PKSA - Deprecated since protocol V1

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.

The APP must then encrypt the auth_req_data object using the auth_key (see Encryption Key)

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

auth_req

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

Properties

• account: the Hive account name that the application wants to authenticate

• data: the Base64 representation of an encrypted auth_req_data object

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.

When using a PKSA running in Service Mode, 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:

{ cmd: "auth_req", account: "username", data: {{encrypted_data_base64}}, auth_key: CryptoJS.Encrypt(auth_key, auth_req_secret) }

The HAS will reply with an auth_wait message

auth_wait

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

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