Organizations ************* Register a new Organization --------------------------- .. raw:: html
POST /api/v1/orgsExample ^^^^^^^ :: { "org": "modilabs", "name": "Modi Labs Research", "email": "modilabs@localhost.com", "city": "New York", "country": "US", ... } List of Organizations --------------------- .. raw:: html
GET /api/v1/orgsExample ^^^^^^^ :: curl -X GET https://api.ona.io/api/v1/orgs Response ^^^^^^^^ :: [ { "url": "https://api.ona.io/api/v1/orgs/modilabs", "org": "modilabs", "name": "Modi Labs Research", "email": "modilabs@localhost.com", "city": "New York", "country": "US", "website": "", "twitter": "", "gravatar": "https://secure.gravatar.com/avatar/xxxxxx", "require_auth": false, "user": "https://api.ona.io/api/v1/users/modilabs", "creator": "https://api.ona.io/api/v1/users/demo" }, ... ] List of Organizations Shared with Another User ---------------------------------------------- .. raw:: html
GET /api/v1/orgs?shared_with={username}
Example
^^^^^^^
::
curl -X GET https://api.ona.io/api/v1/orgs?shared_with=username
Get a paginated list of Organizations (v2)
------------------------------------------
Version 2 of the organizations API is served at ``/api/v2/orgs``. It supports registering, retrieving, updating and deleting an organization, and managing its members.
Returns a list of the organizations you have access to, using page number and the number of items per page. Use the ``page`` parameter to specify page number and ``page_size`` parameter is used to set the custom page size.
- ``page`` - Integer representing the page.
- ``page_size`` - Integer representing the number of records that should be returned in a single page. The maximum number of items that can be requested in a page via the ``page_size`` query param is 10,000
Organizations are listed alphabetically by their username (the ``org`` field). When neither parameter is supplied, the first 1,000 organizations are returned.
The response body is a list. Links to the ``first``, ``prev``, ``next`` and ``last`` pages are returned in the ``Link`` response header, where they apply.
.. raw:: html
GET /api/v2/orgs?Example ^^^^^^^ :: curl -X GET "https://api.ona.io/api/v2/orgs?page=1&page_size=2" Response headers ^^^^^^^^^^^^^^^^ :: Link:page=1&page_size=2
GET /api/v2/orgs?Example ^^^^^^^ :: curl -X GET https://api.ona.io/api/v2/orgs?search=health ``search`` can be combined with ``role``, ``shared_with``, ``page`` and ``page_size``. Example ^^^^^^^ :: curl -X GET "https://api.ona.io/api/v2/orgs?search=health&shared_with=username&page=1&page_size=20" Filter Organizations by your role (v2) -------------------------------------- Use the ``role`` parameter to return only the organizations where you, the requesting user, hold that role or a higher one. For example, ``role=manager`` returns the organizations you manage or own. ``role`` accepts ``member`` and any role a member of an organization can be given: ``owner``, ``manager``, ``editor``, ``editor-minor``, ``editor-no-download``, ``dataentry``, ``dataentry-minor``, ``dataentry-only``, ``readonly`` and ``readonly-no-download``. Any other value returns a ``400`` error. - ``owner`` - organizations you own. - ``manager`` - organizations you manage or own. - ``editor`` down to ``readonly`` - organizations where you have been given a role. These roles all carry the same access to an organization, so they return the same organizations. They are the ones where your ``role`` among the organization's members is ``editor``, ``manager`` or ``owner``. - ``member`` and ``readonly-no-download`` - every organization you belong to. This is the same as leaving ``role`` out. .. raw:: htmlsearch={term}
GET /api/v2/orgs?Example ^^^^^^^ :: curl -X GET https://api.ona.io/api/v2/orgs?role=manager ``role`` can be combined with ``search``, ``shared_with``, ``page`` and ``page_size``. Example ^^^^^^^ :: curl -X GET "https://api.ona.io/api/v2/orgs?role=manager&search=health&page=1&page_size=20" Retrieve Organization Profile Information ----------------------------------------- .. raw:: htmlrole={role}
GET /api/v1/orgs/{username}
Example
^^^^^^^
::
curl -X GET https://api.ona.io/api/v1/orgs/modilabs
Response
^^^^^^^^
::
{
"url": "https://api.ona.io/api/v1/orgs/modilabs",
"org": "modilabs",
"name": "Modi Labs Research",
"email": "modilabs@localhost.com",
"city": "New York",
"country": "US",
"website": "",
"twitter": "",
"gravatar": "https://secure.gravatar.com/avatar/xxxxxx",
"require_auth": false,
"user": "https://api.ona.io/api/v1/users/modilabs",
"creator": "https://api.ona.io/api/v1/users/demo"
}
Retrieve Organization Profile Information (v2)
----------------------------------------------
``current_user_role`` is your role in the organization: ``owner``, ``manager``, ``editor`` or ``member``. It is ``null`` if you do not belong to the organization or are not logged in. It is also returned when an organization is registered or updated.
``email``, ``metadata`` and ``encryption_keys`` are only returned to the organization's owners and managers. To get the organization's members, see `List Organization members (v2)`_.
.. raw:: html
GET /api/v2/orgs/{username}
Example
^^^^^^^
::
curl -X GET https://api.ona.io/api/v2/orgs/modilabs
Response
^^^^^^^^
::
{
"url": "https://api.ona.io/api/v2/orgs/modilabs",
"org": "modilabs",
"user": "https://api.ona.io/api/v1/users/modilabs",
"email": "modilabs@localhost.com",
"creator": "https://api.ona.io/api/v1/users/demo",
"metadata": {},
"name": "Modi Labs Research",
"encryption_keys": [],
"city": "New York",
"country": "US",
"home_page": "",
"twitter": "",
"description": "",
"require_auth": false,
"address": "",
"phonenumber": "",
"num_of_submissions": 0,
"date_modified": "2026-09-18T12:00:00.000000Z",
"current_user_role": "owner"
}
Partial updates of Organization Profile Information
---------------------------------------------------
Organization profile properties can be updated using ``PATCH`` http
method. Payload required is for properties that are to be changed in
JSON, for example , ``{"metadata": {"computer": "mac"}}`` will set the
metadata to ``{"computer": "mac"}``.
.. raw:: html
PATCH /api/v1/orgs/{username}
Example
^^^^^^^
::
curl -X PATCH -d ‘{“metadata”: {“computer”: “mac”}}’https://api.ona.io/api/v1/profiles/modilabs -H “Content-Type: application/json”
Response
^^^^^^^^
::
{
"url": "https://api.ona.io/api/v1/orgs/modilabs",
"org": "modilabs",
"name": "Modi Labs Research",
"email": "modilabs@localhost.com",
"city": "New York",
"country": "US",
"website": "",
"twitter": "",
"gravatar": "https://secure.gravatar.com/avatar/xxxxxx",
"require_auth": false,
"metadata": {
"computer": "mac"
},
"user": "https://api.ona.io/api/v1/users/modilabs",
"creator": "https://api.ona.io/api/v1/users/demo"
}
List Organization members
-------------------------
Get a list of organization members.
.. raw:: html
GET /api/v1/orgs/{username}/members
Example
^^^^^^^
::
curl -X GET https://api.ona.io/api/v1/orgs/modilabs/members
Response
^^^^^^^^
::
["member1", "member2"]
List Organization members (v2)
------------------------------
Get a list of organization members, each with their role in the organization. Members are listed alphabetically by username, and owners are included.
.. raw:: html
GET /api/v2/orgs/{username}/members
Example
^^^^^^^
::
curl -X GET https://api.ona.io/api/v2/orgs/modilabs/members
Response
^^^^^^^^
::
[
{
"user": "member1",
"role": "owner",
"first_name": "Member",
"last_name": "One",
"gravatar": "https://secure.gravatar.com/avatar/xxxxxx"
},
{
"user": "member2",
"role": "member",
"first_name": "Member",
"last_name": "Two",
"gravatar": "https://secure.gravatar.com/avatar/xxxxxx"
}
]
Add, update and remove Organization members (v2)
------------------------------------------------
An owner of the organization adds a member, changes the role of a member and removes a member. The member is sent as JSON in the request body.
- ``username`` - The username of the member. Required.
- ``role`` - The role of the member: ``owner``, ``manager``, ``editor``, ``editor-minor``, ``editor-no-download``, ``dataentry``, ``dataentry-minor``, ``dataentry-only``, ``readonly`` or ``readonly-no-download``. Optional when adding a member. Required when updating a member, unless the member is being removed.
- ``remove`` - When updating a member, ``true`` removes the member from the organization.
- ``email_msg`` and ``email_subject`` - An email with this message is sent to the member. ``email_subject`` is optional.
A member is added with ``POST``. The role of a member is changed, or the member is removed, with ``PUT`` or ``PATCH``. Adding or updating a member returns the member, as in `List Organization members (v2)`_. Removing a member returns ``204 No Content``.
.. raw:: html
POST /api/v2/orgs/{username}/members
PUT /api/v2/orgs/{username}/members
PATCH /api/v2/orgs/{username}/members
Example
^^^^^^^
Add a member, change the member's role, then remove the member.
::
curl -X POST -d '{"username": "member1", "role": "editor"}' https://api.ona.io/api/v2/orgs/modilabs/members -H "Content-Type: application/json"
curl -X PATCH -d '{"username": "member1", "role": "manager"}' https://api.ona.io/api/v2/orgs/modilabs/members -H "Content-Type: application/json"
curl -X PATCH -d '{"username": "member1", "remove": true}' https://api.ona.io/api/v2/orgs/modilabs/members -H "Content-Type: application/json"
Response
^^^^^^^^
The response to adding the member:
::
{
"user": "member1",
"role": "editor",
"first_name": "Member",
"last_name": "One",
"gravatar": "https://secure.gravatar.com/avatar/xxxxxx"
}
Add a user to an organization
-----------------------------
To add a user to an organization requires a JSON payload of
``{"username": "member1"}``. You can add an optional parameter to define
the role of the user.\ ``{"username": "member1", "role": "editor"}``
.. raw:: html
POST /api/v1/orgs/{username}/members
Example
^^^^^^^
::
curl -X POST -d '{"username": "member1"}' https://api.ona.io/api/v1/orgs/modilabs/members -H "Content-Type: application/json"
Response
^^^^^^^^
::
["member1"]
Send an email to a user added to an organization
------------------------------------------------
An email is only sent when the ``email_msg`` request variable is
present, ``email_subject`` is optional.
.. raw:: html
POST /api/v1/orgs/{username}/members
Example
^^^^^^^
::
curl -X POST -d '{"username": "member1", "email_msg": "You have been added to Ona", "email_subject": "Your have been added"}' https://api.ona.io/api/v1/orgs/modilabs/members -H "Content-Type: application/json"
Response
^^^^^^^^
::
["member1"]
Change the role of a user in an organization
--------------------------------------------
To change the role of a user in an organization pass the username and
role ``{"username": "member1", "role": "owner|manager|editor|dataentry|readonly"}``.
.. raw:: html
PUT /api/v1/orgs/{username}/members
Example
^^^^^^^
::
curl -X PUT -d '{"username": "member1", "role": "editor"}' https://api.ona.io/api/v1/orgs/modilabs/members -H "Content-Type: application/json"
Response
^^^^^^^^
::
["member1"]
Remove a user from an organization
----------------------------------
To remove a user from an organization requires a JSON payload of
``{"username": "member1"}``.
.. raw:: html
DELETE /api/v1/orgs/{username}/members
Example
^^^^^^^
::
curl -X DELETE -d '{"username": "member1"}' https://api.ona.io/api/v1/orgs/modilabs/members -H "Content-Type:application/json"
Response
^^^^^^^^
::
[]
Rotate a KMS key manually
-------------------------
.. raw:: html
POST /api/v1/orgs/{username}/rotate-key
Example
^^^^^^^
::
curl -X POST https://api.ona.io/api/v1/orgs/modilabs/rotate-key \
-d '{
"id": "67",
"rotation_reason": "Automatic rotation failed"
}'
Response
^^^^^^^^
::
{
"id": "68",
"description": "Key-2025-05-09",
"date_created": "2025-05-09T00:00:00Z",
"is_active": true,
"is_expired": false,
"expiry_date": "2026-05-09T00:00:00Z",
"grace_end_date": "2026-06-09T00:00:00Z",
"is_automatic": false,
}