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.