Authentication

Learn how to authenticate in Onna using the API

💡 3 min read

# Requirements

Authentication requires that you have an Onna account. You can sign up for an Onna account by filling out the registration form.

import json
import requests

base_url = 'https://enterprise.onna.com'
oauth_path = '/auth/oauth/'
user = "user@domain.com"
container = "container"
account = "account"

resp = requests.get(f'{base_url}/api/{container}/{account}/@oauthgetcode?client_id=canonical&scope={account}')
auth_code = resp.json()['auth_code']
print(f"auth_code: {auth_code}")

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

The response should have a value for auth_code, it is required for the next leg of the authentication flow:

auth_code: xxxxx...

Info

scope is the name of your account.

container is the name of the database attached to your account.

Our naming convention is to use the account name you provided during the self-registration process.

scope, container, and account may be the same value.

You now have the first leg of our authentication process. Next, use your Onna credentials to get a token, passed in subsequent request headers.

payload = {'grant_type': "user",
           'code': auth_code,
           'username': "user@domain.com",
           'password': 'your-password',
           'scopes': [f"{account}"],
           'client_id': "canonical"
          }
headers = {'Accept': 'application/json'}
resp = requests.post(f'{base_url}/{oauth_path}/get_auth_token', headers=headers, data=json.dumps(payload))
jwt_token = resp.text
print(f"jwt_token: {jwt_token}")

1
2
3
4
5
6
7
8
9
10
11

Using the token, you now have access to the rest of the API. Let's make sure that the token works by retrieving your account information via the me endpoint.

You'll set the headers so that you can reuse it in subsequent requests to the API.

headers = {'Accept': 'application/json', 'Authorization': "Bearer {}".format(jwt_token)}
resp = requests.post(f'{base_url}/{oauth_path}/me', headers=headers)

1
2

The response resp.json() should look something like this:

{'blocked': False,
 'groups': [],
 'id': 'user@domain.com',
 'mail': 'user@domain.com',
 'name': 'user@domain.com',
 'resetPassword': False,
 'roles': [],
 'surname': 'you'}

1
2
3
4
5
6
7
8

You can also inspect your user object, which is also a container for data that you own in the Onna platform.

resp = requests.get(f"{base_url}/api/{container}/{account}/{user}", headers=headers)
print(f"{user}: {resp.json()}"

1
2

The response will look similar to this:

{
    '@id': 'https://enterprise.onna.com/api/container/account/user@domain.com',
    '@type': 'User',
    '@name': 'user@domain.com',
    '@uid': 'f3192ce32d404456a828929180071161',
    '@static_behaviors': ['onna.canonical.behaviors.following.IFollowing'],
    'parent':
        {'@id': 'https://enterprise.onna.com/api/rel0/account1',
        '@name': 'account',
        '@type': 'Container',
        '@uid': '36e968b2cc1641b8a4e7536e3c2bbc7b'},
        'is_folderish': True,
        'creation_date': '2020-03-11T13:00:25.072437+00:00',
        'modification_date': '2020-03-11T13:00:25.073475+00:00',
        'machines': [],
        'facets': None,
        'columns': None,
        'type_name': 'User',
        'title': None,
        'uuid': 'f3192ce32d404456a828929180071161',
        '__behaviors__': [],
        'onna.canonical.behaviors.following.IFollowing':
            {'favorites': [],
            'favorite': False},
            'parent_datasource': None,
            'parent_user':
                {'id': 'user@domain.com',
                'title': None,
                'path': '/user@domain.com',
                'uuid': 'f3192ce32d404456a828929180071161'},
                'parent_group': None,
                'parent_workspace': None,
                'in_legal_hold': False}
}

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

Additionally, you can get information about your account via the @statusAccount endpoint

resp = requests.get(
    f"{base_url}/api/{container}/{account}/@statusAccount", headers=headers
)
print(f"Account status: {resp.json()}")

1
2
3
4

The output will look similar to this:

{
    'account_type': 'standard',
    'trial_status': None,
    'trial_start_date': None,
    'trial_remaining_days': None,
    'trial_finished_at': None,
    'datasources_count': 72,
    'total_space_mb': 1083.72,
    'num_users_current': 5,
    'disk_quota_limit': None,
    'current_connected_sources': 40139,
    'current_trial_connected_sources': 0,
    'max_connected_sources': None,
    'over_resource_limit': False,
    'workspaces_count': 32
}

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

# Recap

You learned about authentication, retrieving and reusing the auth token as part of our header for requests passed to the Onna API.

You pulled some basic information about the requesting user and the user's account.

In the next chapter, you'll set up a static Datasource, upload some files to it, and run a search on the uploaded files.

← Hello world Create a static Datasource →