# API Key Auth Flow

# Getting Started

Authentication via api keys is your preferred solution for creating integrations to Tillhub. You leave the account owner the full control, and if you are the account owner, you can always disarm your tokens via deleting them, once they are compromised.

Also this allows to swap accounts in your integrations easily. Making them available for multiple users or customers at a time.

To use the API Key authentication flow, you first need to procure a API Key that usually follows the pattern of an uuidv4. This API Key needs to be send, together with the account ID, to the authentication endpoint (see example below). If you are not the owner of the account, or do not have the permissions to create keys (within the Tillhub Dashboard: Account & Settings -> General -> Users -> API (opens new window)), you have to ask a Tillhub Account admin to issue the API Key.

# Authentication

# Example Request

curl -X POST \
  https://api.tillhub.com/api/v1/users/auth/key \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "YourUserAccountID",
    "api_key": "YourAPIKey"
}'
1
2
3
4
5
6
7

# Response Object

{
    "status": 200,
    "msg": "Authentication was good.",
    "request": {
        "host": "api.tillhub.com",
        "id": "034bf4f9-4107-4bc0-bdab-882cae7d3e08"
    },
    "user": {
        "id": "YourUserAccountID",
        "name": "YourAccoundName",
        "legacy_id": "ForAccountsBefore2018"
    },
    "token": "YourJW-Token",
    "token_type": "Bearer",
    "sub_user": {
        "id": "dd77cd17-b0b6-408a-87c2-09dc88ad5145",
        "created_at": "2020-03-25T10:30:58.052Z",
        "updated_at": "2020-03-25T10:30:58.176Z",
        "metadata": null,
        "groups": null,
        "scopes": null,
        "attributes": null,
        "user": {
            "id": null,
            "email": null
        },
        "description": "API User",
        "active": true,
        "role": "serviceaccount",
        "parents": null,
        "children": null,
        "blocked": false,
        "configuration_id": "6bcf2faa-b618-4b00-b12a-2a8bba9a9b31",
        "user_id": null,
        "deleted": false,
        "api_key": "81f7f582-b3e9-4912-b45a-fdf23bdf3fc5",
        "key": null,
        "username": null,
        "name": "Test",
        "locations": null
    },
    "expires_at": "2020-05-28T07:28:44.000Z"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

# Making a call

In order to make a call to the Backend, utilise the Bearer token returned by the authentication endpoints. E.g. in the products tutorials..