Authenticating Requests

Almost every request to Crossbar must be sent with authentication credentials.

Failing to do so will result in in 401 Unauthorized HTTP response status with a response payload like this:

{
  "data": {
    "message": "invalid credentials"
  },
  "error": "401",
  "message": "invalid_credentials",
  "status": "error",
  "timestamp": "{TIMESTAMP}",
  "version": "{VERSION}",
  "node": "{API_NODE}",
  "request_id": "{REQUEST_ID}",
  "auth_token": "{AUTH_TOKEN}"
}

Crossbar provides a number of ways of authenticating request.The most common way is to authenticate as a user and receive a token that can be used on subsequent requests.

Basic Authentication

This is very simple and quick way of authentication. In this method, you have to add an Authorization HTTP header to request. The authorization method is Basic and the value is concatenation of your account ID and md5 hash of username and password. Refer to Basic Authentication for more information on how to generate the value for Authorization header.

Basic authentication has a disadvantage in that you have to provide the username and password in unencrypted text for every request.

Token based Authentication

This is the preferred and more secure way to do authentication with Crossbar API.

In Token based authentication you have to login first to get a token which you can then use in other requests. The token should be set in X-Auth-Token HTTP header in subsequent requests.

The are different ways to do login authentication.

Authenticate as a User

This is the best way to get authenticated and get the token for UI applications for manual requests.

In this method, you provide the credentials of your user just for login and crossbar will generate an authentication token in response.

User credentials is MD5 hash of USERNAME:PASSWORD. So for example if the username is john@example.com and the password is m32c6NfqYEt MD5 hash of john@example.com:m32c6NfqYEt (note the colon : which separates the username and password) is 82a2dc91686ec828a67152d45a5c5ef7.

Note

When hashing, the username must be converted to all lowercase characters before computing the hash.

For generating the MD5 of a text in terminal you can use md5sum (in Linux) or md5 (in macOS) like this:

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

NOTE: You can also use more secure SHA1 as your hash function. For generating SHA1 hash in terminal use shasum command.

If you are using a programming language, refer to its documentation on how to generate MD5 hash.

You also need another field of data to identify the user: account’s name or account’s realm or phone number assigned to this user.

After the required data is ready, you can use user_auth API to get an authentication token:

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

And a successful response:

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

Here {AUTH_TOKEN}, the authentication token, is a long list of characters which you can use in future requests.

curl -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

See User Authentication to learn more about this API resource.

Account API Authentication

Uses your account’s API token to generate authentication token. If you’re building server applications, this is the best way to authenticate your application.

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

curl -X PUT \
    -d '{"data": {"api_key":"{API_KEY}"} }' \
    http://{SERVER}:8000/v2/api_auth

You can find the API key in Authentication application in UI, or you can get it using Accounts API.

Next Steps

There are more ways to authenticate your request. Learn more about them in Authentication APIs section.

On this page