Authentication in the API

The Dash API requires an authentication token on each request. A user auth call turns a hashed username and password, plus the account name, into that token. A server should call api_auth with the account API key instead of a person's password. Reuse the token across a series of requests. It expires after a period of inactivity, so create a new one when the API rejects the old token.

About Authentication

The Dash API requires you to provide an authentication token with each request.

Using your username and password, along with an account company, you may issue an API call to user_auth to generate an authentication token.

Using your account’s API token you may issue an API call to api_auth to generate an authentication token. If you’re building server applications, this is the best way to authenticate your application.

This is the same as authenticating as a user, except you supplying the API key as data.

Once an authentication token is generated, it may be used for subsequent API calls. The Token will expire after a period of inactivity. You may reuse the same token for a series of API requests.

Creating User Auth Token

When creating an Authentication Token, you must hash the password prior to submitting the user_auth request.

API

Method: PUT

https://public-api.virtualpbx.com:8443/v2/user_auth

Payload

{
  "data": {
    "credentials": "{{password_hash}}",
    "account_name": "{{account_name}}"
  }
}

Hash the user credentials

On Unix-like systems using Shell:

PASSWORD=`echo -n username:password | md5sum | awk '{print $1}'`

On Windows using PowerShell:

[BitConverter]::ToString((New-Object System.Security.Cryptography.MD5CryptoServiceProvider).ComputeHash([System.Text.Encoding]::UTF8.GetBytes("username:password"))).Replace('-', '').ToLower()

The following request will create an authentication token. The string in auth_token field contains the authentication token.

Request response

JSON

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "account_id": "{ACCOUNT_ID}",
        "apps": [],
        "is_reseller": true,
        "language": "en-US",
        "owner_id": "{OWNER_ID}",
        "reseller_id": "{RESELLER_ID}"
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

CURL Example

curl --location --request PUT 'https://public-api.virtualpbx.com:8443/v2/user_auth' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "credentials": "{{password_hash}}",
    "account_name": "{{account_name}}"
  }
}'