API authentication

The preferred method of authenticating the API user is using token authentication with a user-specific access token.

For trying out the API and for situations where using token authentication is not feasible, Custobar supports Basic authentication with a username and password.

Token authentication

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

An access token can be acquired from the 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.

{
  "token": "APIUXFYECFVWDYKTETRA3DOTX7BFJXMDNWR4QBAP"
}

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 APIUXFYECFVWDYKTETRA3DOTX7BFJXMDNWR4QBAP" \
  -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

You can authenticate with the API using your Custobar username and password, 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 in your configuration.

Two-factor authentication

If two-factor authentication is enabled, authenticating with the api using username and password is not allowed. In this case, you must use token authentication. However, if you really need to, for example, if you are writing a configuration tool that first exchanges username and password to an access token, you can supply the current value of the two-factor authentication code with a custom Custobar-TOTP-Code header, in addition to the regular basic authentication header.

So if your username is “bob”, password is “pAssw0rd”, and two-factor authentication app shows code 012345, send the following headers:

Authorization: Basic Ym9iOnBBc3N3MHJk
Custobar-TOTP-Code: 012345

Using access token with basic authentication

Some systems don’t allow setting custom authorization header for requests, but do allow basic authentication. In this case, you can still use token authentication, by setting username as “access-token” and using the api token as password.