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 accountSCOPE
is the name of your Onna account. For more info, see the glossary.
The response will contain your auth code.
{
"auth_code": "d3m0dem0f4kefak3d3m0f4k3d3m0d3m0f4k3"
}
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 stepUSERNAME
is the email you signed up withPASSWORD
is your super-secret account passwordSCOPE
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
}
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 accountACCOUNT
is the name of your Onna accountUSERNAME
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
}
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
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18