How to authenticate

💡 5 min read

Learn how to authenticate in Onna using the API

Authentication is a two-step process where you first retrieve an auth code and then use it to get your auth token. When you have the auth token you add it to your headers to make other API calls.

If you prefer Python

You can use the effortless Python authentication script (opens new window) for automation. The script authenticates and queries some endpoints to confirm authentication.

Make sure your setup meets all the requirements before running the script.

# Requirements

An active account. You can create one from the [trial signup page](https://register.onna.com/signup?trial=true "Onna trial account signup page".

# Get auth code

Make a GET request to the @oauthgetcode endpoint.

Replace these values:

CONTAINER is the Database where your data is hosted. It usually matches the name of your organization's account. For example, acmecorp
ACCOUNT is the name of your organization's account. For example, acmecorp
SCOPE is the name of your organization's account. For example, acmecorp

The full URL should look like:

https://enterprise.onna.com/api/acmecorp/acmecorp/@oauthgetcode?client_id=canonical&scope=acmecorp

The response will contain your auth code.

{
    "auth_code": "d3m0dem0f4kefak3d3m0f4k3d3m0d3m0f4k3"
}

1
2
3

# Get auth token

Make a POST request to the get_auth_token endpoint.

The request must include your auth code, your username, and your password, among other information.

Replace these values:

CODE is the auth code you retrieved in the previous step
USERNAME is the email you signed up with
PASSWORD is your super-secret account password
SCOPE is the name of your organization's account. For example, acmecorp

The response will contain your bearer token.

f4k3eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2MDc2MTAxODIsImV4cCI6MTYwODIxNDk4MiwidG9rZW4iOiI5ZmNkMzcwYmFiYWE0MGM0ODQ1ZjY2NDRkYzM5OTRmZiIsImxvZ2luIjoic3RlZmFub0Bvc2NpbGxhdG9yLmVzIiwibmFtZSI6IlN0ZWZhbm8iLCJzdXBlcnVzZXIiOmZhbHNlLCJhaWQiOm51bGwsInN1YiI6InN0ZWZhbm9Ab3NjaWxsYXRvci5lcyIsImF2IjoxLCJndCI6ImF1dGhvcml6YXRpb25fY29kZSJ9.-2rA45w9MzvYAsrBgTgk_P5t5lmbPiJG38VlNo6d3m0

# Add token to API calls

You can now call other API endpoints by including the bearer token in your request header.

For example, test the authentication by making a POST request to the me endpoint, which contains your user information.

A successful response will contain your user information.

Expand to see the example

{
    "roles": [],
    "groups": [],
    "permissions": [],
    "mail": "USERNAME",
    "id": "USERNAME",
    "surname": "Scott",
    "name": "Michael",
    "blocked": false,
    "resetPassword": false,
    "data": {},
    "totp_enabled": false,
    "avatar": "",
    "scope-mfa-required": false
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Other ways to test auth

You can also test authentication by making a GET request to your user folder, which is a container for data that you own in the platform and where you can perform create, read, update, and delete operations.

Replace these values:

CONTAINER is the Database where your data is hosted. It usually matches the name of your organization's account. For example, acmecorp
ACCOUNT is the name of your organization's account. For example, acmecorp
USERNAME is the email you signed up with

The response will list the data you own in the platform.

Expand to see the example

{
    "@id": "https://enterprise.onna.com/api/container/account/USER",
    "@type": "User",
    "@name": "USER",
    "@uid": "f4k3673c32d245ffb70eb15cff9ed3m0",
    "@static_behaviors": [
        "onna.canonical.behaviors.following.IFollowing"
    ],
    "parent": {
        "@id": "https://enterprise.onna.com/api/container/account/USERNAME",
        "@name": "container",
        "@type": "Container",
        "@uid": "d3m0b1d6334943ddae3b6fdd1024f4k3"
    },
    "is_folderish": true,
    "creation_date": "2020-12-10T11:19:08.441098+00:00",
    "modification_date": "2020-12-10T11:19:08.441439+00:00",
    "machines": [],
    "facets": null,
    "columns": null,
    "type_name": "User",
    "title": "Michael Scott",
    "uuid": "f4k3673c32d245ffb70eb15cff9ed3m0",
    "__behaviors__": [],
    "onna.canonical.behaviors.following.IFollowing": {
        "favorites": [],
        "favorite": false
    },
    "parent_datasource": null,
    "parent_user": {
        "id": "USERNAME",
        "title": "Michael Scott",
        "path": "/USERNAME",
        "uuid": "f4k3673c32d245ffb70eb15cff9ed3m0"
    },
    "parent_workspace": null
}

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

Finally, you can also test the authentication by sending a GET request to the @statusAccount endpoint, which gives information about the status of your organization's account.

Replace these values:

CONTAINER is the Database where your data is hosted. It usually matches the name of your organization's account. For example, acmecorp
ACCOUNT is the name of your organization's account. For example, acmecorp

The response will list information about the status of your organization's account.

Expand to see the example

{
    "account_type": "signup",
    "trial_status": "trialing",
    "trial_start_date": "2020-12-10T11:19:14.590624",
    "trial_remaining_days": 30,
    "trial_finished_at": null,
    "datasources_count": 0,
    "num_users_current": 1,
    "disk_quota_limit": 100,
    "current_connected_sources": 0,
    "current_trial_connected_sources": 0,
    "max_connected_sources": 10,
    "over_resource_limit": false,
    "workspaces_count": 0,
    "processed_mb": 0.0,
    "payment_info": false,
    "pay_immediately": true
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

← Hello world Create a static Datasource →