Please make sure you read the Conventions before continuing with this guide.

Requirements.

You will need an X-API-KEY for all steps.

Login with a customer.

You will interact with the /accounts/customers endpoint of the Accounts Bucket.

This step will require an additional header, Authorization, which will be assigned the value of Basic appended with {{customerNumber}}:{{customer-password}} encoded in base64.

If you want to use the email you replace the customerNumber with the email {{email}}:{{customer-password}} encoded in base64. You need to make sure the customer has loginByEmail enable to be able to login this way.

echo -n "user@btrz.com:secret1" | base64
// dXNlckBidHJ6LmNvbTpzZWNyZXQx

We will call it base64-encoded-username-and-pwd.

Ie. 'Basic dXNlckBidHJ6LmNvbTpzZWNyZXQx'

When successful, a json customer and provider object as well as tokens will be returned.

Response :

{
    "customer": {
        "_id": "afa5678abbfa19132018942p",
        "customerNumber": "999-999-999",
        "accountId": "a2a377ec430c7d4e220001fl",
        "agencyId": "",
        "firstName": "John",
        "lastName": "Smith",
        "email": "j-smith@example.com",
        "phone": "",
        "normalizedPhone": "",
        "phoneType": "",
        "street": "1 main street",
        "city": "The six",
        "countryId": "CA",
        "country": "Canada",
        "province": "ON",
        "zip": "M1M1M1",
        "activeCustomerAccount": true,
        "cloutCategory": "Newbie",
        "clout": {
            "p0000_00": {
                "purchases": 2,
                "travels": 0,
                "purchasesValue": 2735000,
                "travelsValue": 0
            },
            "p2020_11": {
                "purchases": 2,
                "travels": 0,
                "purchasesValue": 2735000,
                "travelsValue": 0
            }
        },
        "deleted": false,
        "optIn": true,
        "createdAt": {
            "value": "2020-11-06T15:11:06.986Z",
            "offset": 0
        },
        "updatedAt": {
            "value": "2022-12-08T20:08:49.484Z",
            "offset": 0
        },
        "mergedFrom": [],
        "mergedTo": "",
        "enrolledInLoyaltyProgram": false,
        "ssoId": "",
        "ssoProviderId": "",
        "externalId": "",
        "travellers": [],
        "dob": "",
        "emailAndPwdLoginConfigured": true,
        "emailAndPwdLoginActive": true,
        "mustResetPassword": false,
        "premium": [
        ]
    },
    "token": "long-token-string",
    "shortToken": "jwt-short-token"
}

Notes

Now that a customer has been successfully logged in, you can use the "shortToken" value returned in the response to call other endpoints that the customer is authorized to access.

For example, to call the operations/transactions endpoint, you would add a querystring parameter with the customer number:

https://api.betterez.com/operations/transactions/?customer=123-123-123

In the headers, you would provide the x-api-key in addition to a new Authorization header, similar to the one provided before, 'authorization: Bearer {{jwt-short-token}}'.

Token expiration

The customer token expires after 2 days. The JWT is used as a stateless Authentication mechanism and so there isn't an endpoint you can use to invalidate or logout. If you are building an application you can maintain a session on your own servers, store the JWT in the session at the server level and use the server to interact with our API. Your application can provide a signout mechanism that destroys the session in your servers thus destroying the token.