How to authenticate

Learn how to authenticate in Onna using the API

💡 4 min read

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 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

# Get auth code

Make a GET request to the @oauthgetcode endpoint.

Make sure to include the client_id and scope parameters in your request.

Where:

CONTAINER is the name of your Onna account. For more info, see the glossary.
ACCOUNT is the name of your Onna account
SCOPE is the name of your Onna account. For more info, see the glossary.

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 and your username and password, among other information.

Where:

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 Onna account

The response will include 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 show 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

Another way you can test authentication is 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.

Where:

CONTAINER is the name of your Onna account
ACCOUNT is the name of your Onna account
USERNAME is the email you signed up with

The response will show which 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.

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 →