Skip to content

KAZOO Support Channels

This documentation is curated by 2600Hz as part of the KAZOO open source project. Join our community forums here for peer support. Only features in the docs.2600hz.com/supported space are included as part of our 2600Hz Support Services plan.

User Authentication#

About User Authentication#

Using your user name and password, along with an account identifier, will instruct Crossbar to create an authentication token to be used on subsequent requests requiring authentication.

Schema#

Provides an auth-token via user credentials

Key Description Type Default Required Support Level
account_name The account name of the user string(1..128) false
account_realm The account realm of the user string(4..253) false
credentials A hash of the user credentials string(1..64) true
method The hash method string('md5' | 'sha') md5 false
phone_number A phone number assigned to the users account string(1..64) false

Create#

PUT /v2/user_auth

curl -v -X PUT \
    -H "Content-Type: application/json" \
    -d '{"data":{"credentials":"{CREDENTIALS_HASH}", "account_name":"{ACCOUNT_NAME}", "method":"[md5|sha]"}}' \
    http://{SERVER}:8000/v2/user_auth

Where {CREDENTIALS_HASH} is MD5 or SHA1 hash of {username}:{password}.

Creating MD5 User/Pass credentials hash#

$ echo -n 'john@example.com:m32c6NfqYEt' | md5sum
82a2dc91686ec828a67152d45a5c5ef7  -

Creating SHA1 User/Pass credentials hash#

$ echo -n 'john@example.com:m32c6NfqYEt' | sha1sum
055cf886cb9b5c5867083463867c527ace0f8ecc  -

Responses

{
    "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"
}

Fetch Token Auth Information#

GET /v2/user_auth/{AUTH_TOKEN}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/user_auth/{AUTH_TOKEN}
{
    "data": {
        "account_id": "{ACCOUNT_ID}",
        "owner_id": "{USER_ID}",
        "method": "cb_user_auth",
        "id": "{AUTH_TOKEN}",
        "reseller_id": "{RESELLER_ID}",
        "is_reseller": false,
        "account_name": "{ACCOUNT_NAME}",
        "language": "en-us",
        "apps": [{
            "id": "8bda62bf7ccf8f8acc219d5d2c515376",
            "name": "accounts",
            "api_url": "http://192.168.0.2:8000/v2/",
            "label": "Accounts Manager"
        }, {
            "id": "99d5f033f0a4176640f9bf1c4e81abed",
            "name": "numbers",
            "api_url": "http://192.168.0.2:8000/v2/",
            "label": "Number Manager"
        }, {
            "id": "0306d5162bad2c7a951b6842483f73cd",
            "name": "voip",
            "api_url": "http://192.168.0.2:8000/v2/",
            "label": "Smart PBX"
        }]
    },
    "auth_token": "{AUTH_TOKEN}",
    "status": "success"
}

Password Recovery#

Sometimes it is necessary to recover a password. Similar to user authentication, you can supply the account realm, the account name, or a phone number associated with the account to send a password reset to the user's email. This email will contain a link that one then click to verify identity & proceed with recovery.

Schema#

Send a reset-your-password email via user credentials

Key Description Type Default Required Support Level
account_name The account name of the user string(1..64) false
account_realm The account realm of the user string(1..64) false
phone_number A phone number assigned to the user's account string(1..64) false
ui_url The UI's root URL string(14..2000) true
username The user's username string(1..254) true

API request#

PUT /v2/user_auth/recovery

curl -v -X PUT \
    -H "content-type: application/json" \
    -d '{"data":{"username":"API_USERNAME", "account_realm":"ACCOUNT_REALM", "ui_url": "{UI_URL}"}}' \
    http://{SERVER}:8000/v2/user_auth/recovery
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {},
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Send the {RESET_ID} collected in the recovery-email.

POST /v2/user_auth/recovery

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"reset_id": "{RESET_ID}"}}'
    http://{SERVER}:8000/v2/user_auth/recovery

Responses

Success#

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {},
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Unknown {RESET_ID}#

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "user": {
            "not_found": {
                "cause": "{RESET_ID}",
                "message": "The provided reset_id did not resolve to any user"
            }
        }
    },
    "error": "500",
    "message": "invalid request",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Impersonate a User#

You can impersonate as another user in your sub account if you're already is logged in as an admin in your master account. This features a useful way to login as your customer to debug/test issues with the user system's point of view.

PUT /v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/user_auth

curl -v -X PUT \
    -H "Content-Type: application/json" \
    -d '{ "action": "impersonate_user", "data": {} }' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}/user_auth

Responses

A standard Crossbar authentication token.

{
    "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"
}