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

KeyDescriptionTypeDefaultRequiredSupport Level
account_idThe account ID of the userstring(32)false
account_nameThe account name of the userstring(1..128)false
account_realmThe account realm of the userstring(4..253)false
credentialsA hash of the user credentialsstring(1..64)true
methodThe hash method`string(‘md5''sha’)`md5false
phone_numberA phone number assigned to the users accountstring(1..64)false

Create

Provides an auth-token when provided the user credentials listed above.

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

KeyDescriptionTypeDefaultRequiredSupport Level
account_nameThe account name of the userstring(1..64)false
account_realmThe account realm of the userstring(1..64)false
phone_numberA phone number assigned to the user’s accountstring(1..64)false
ui_urlThe UI’s root URLstring(14..2000)true
usernameThe user’s usernamestring(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 feature is a useful way to login as a customer account to debug/test issues from 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"
}

On this page