« Back to API reference

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 the user’s username and password.

Token authentication

In token authentication, a user-specific access token is passed in 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

A 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 in your configuration.


Previous:
Customers