API authentication

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

Creating an access token

To use the Custobar api, you first need to create an access token to authenticate your requests. Access tokens are created using the Custobar access tokens api.

When creating your first access token, you need to authenticate using HTTP basic authentication with your Custobar username and password. If you have two-factor authentication turned on (as you should have!), you need to provide the current six-digit code as well, using the "Custobar-TOTP-Code" HTTP header.

Creating access token for user "cb.user@example.com" with two-factor authentication turned on using Curl (Custobar plus users make the request to their own Custobar domain instead of app.custobar.com):

curl -X POST \
     -u "cb.user@example.com" \
     -H "Custobar-TOTP-Code: 123456" \
     https://app.custobar.com/api/access-tokens/

(Curl will ask for your password). The result looks like:

{
    "access_token": {
        "id": "6x7jf3e32uvl",
        "owner_id": "users/2",
        "created_at": "2022-10-12T09:47:44Z",
        "name": "",
        "token": "APIXMPLEBT7PIDXTJ6ZD16GQUYWGPVEMEZ67UY92"
    }
}

where the "token" is the value that needs to be sent with every api request.

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.

Authenticating with access token

The access token is sent with every api request in Authorization HTTP header, as a "bearer token", here querying the customers data:

curl -H "Authorization: Bearer APIXMPLEBT7PIDXTJ6ZD16GQUYWGPVEMEZ67UY92" \
     https://app.custobar.com/api/customers/

Access token scope

When setting up another system to send or receive data to Custobar, it is best to limit the integration so that it only has access to the api endpoints it needs to work. This can be done by limiting the access token scope to a single URL, or a set of URLs.

For example, if you set up a datatarget in Custobar so that another system can periodically poll it for new data, you should create a new access token to embed within that system that only has access to that single datatarget. Use the scopes property in the request body to specify the set of scopes avaliable.

Using curl:

curl -X POST \
     -H "Authorization: Bearer APIXMPLEBT7PIDXTJ6ZD16GQUYWGPVEMEZ67UY92" \
     https://app.custobar.com/api/access-tokens/ \
     -H "Content-Type: application/json" \
     -d '{"scopes": [{"path": "/api/datatargets/c8f0iaq7oaj9s/retrieve/"}]}'

The resulting access token only has access for retrieving data from the datatarget with id c8f0iaq7oaj9s.

Basic authentication

In special cases, such as creating the first access token, you can authenticate API requests with your Custobar username and password. This is done using HTTP basic authentication. However, you also need to provide the current value for your two-factor authentication code, using the custom Custobar-TOTP-Code header. See the access token creation example above.

You should not use basic authentication with your username and password in production systems. Instead, only use your username and password to obtain a valid access token. Disadvantages of Basic authentication include inefficiency and need to use plaintext passwords in your configuration.

Alternative ways of passing the access token

Some systems don't allow specifying HTTP headers when configuring requests to other systems. In such cases, it is possible to pass the access token using HTTP basic authentication, or as a url parameter.

Access token as password

If the system your are integrating Custobar API with allows using HTTP basic authentication, you can pass the access token as password, with username being "access-token":

Username: access-token
Password: APIXMPLEBT7PIDXTJ6ZD16GQUYWGPVEMEZ67UY92

Access token as url parameter

If only thing configurable is the request URL, you can pass the access token as a URL parameter:

https://app.custobar.com/api/customers/?access-token=APIXMPLEBT7PIDXTJ6ZD16GQUYWGPVEMEZ67UY92

If other methods (Authorization header or basic authentication) are available, you should use these, and only pass the access token as url parameter if it really is the only option. It is easy leak the token in request logs when it is part of the url, compromising security.