Authentication overview

The preferred method of authenticating the API user is using token authentication with a user-specific access token. However, for trying out the API and for situations where using token authentication is not feasible, Custobar supports basic authentication with the user's username and password.

Token authentication

In token authentication, a user-specific access token is passed in HTTP Authorization header.

The access token can be acquired from Custobar settings, or by using the api itself:

curl -X GET -u USER

The reply to the request is a json object with one property: token.

  "token": "2d928b51b88ac31f0c8fda203770f0cdb1d5926b"

This token is then sent in Authorization header to authenticate without password (Here using it to authenticate customer data import):

 curl -X POST \
    -H "Authorization: Token 2d928b51b88ac31f0c8fda203770f0cdb1d5926b" \
    -H "Content-Type: application/json" \
    --data-binary @customers.json

A user may have one valid access token at a time. The /api/auth/access-token/ api call always returns this valid token. To invalidate the existing token and generate a new one, there is another api call, accepting POST requests:

curl -X POST -u USER

The reply to /api/auth/new-access-token is similar to /api/auth/access-token, but with a new valid token.

Basic authentication

A Custobar user's username and password can be used for authentication, using the standard HTTP basic authentication, as is done in the curl examples above, e.g.

curl -X POST -u USER -H "Content-Type: application/json" \
    --data-binary @customers.json

Using basic authentication is fine for occasional use and testing the API, but for production settings, you should use token authentication. Disadvantages of basic authentication include inefficiency and need to use plaintext passwords. Checking password is resource intesive by design.