« Back to API Documentation

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 https://COMPANY.custobar.com/api/auth/access-token/

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


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

 curl -X POST \
    -H "Content-Type: application/json" \
    --data-binary @customers.json https://COMPANY.custobar.com/api/customers/upload/

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 https://COMPANY.custobar.com/api/auth/new-access-token/

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

Note: Do not create a new access token for each request. Instead, create one token, and the use that token for authentication from that on.

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 https://COMPANY.custobar.com/api/customers/upload/

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 intensive by design.