Organizations¶
Register a new Organization¶
POST /api/v1/orgs
Example¶
{
"org": "modilabs",
"name": "Modi Labs Research",
"email": "modilabs@localhost.com",
"city": "New York",
"country": "US",
...
}
List of Organizations¶
GET /api/v1/orgs
Example¶
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"
},
...
]
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 thepage_sizequery 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.
GET /api/v2/orgs?page=1&page_size=2
Example¶
curl -X GET "https://api.ona.io/api/v2/orgs?page=1&page_size=2"
Response headers¶
Link: <https://api.ona.io/api/v2/orgs?page=2&page_size=2>; rel="next", <https://api.ona.io/api/v2/orgs?page=5&page_size=2>; rel="last"
Response¶
[
{
"url": "https://api.ona.io/api/v2/orgs/healthorg",
"org": "healthorg",
"user": "https://api.ona.io/api/v1/users/healthorg",
"name": "Health Organization",
"date_modified": "2026-09-18T12:00:00.000000Z"
},
{
"url": "https://api.ona.io/api/v2/orgs/modilabs",
"org": "modilabs",
"user": "https://api.ona.io/api/v1/users/modilabs",
"name": "Modi Labs Research",
"date_modified": "2026-09-18T12:00:00.000000Z"
}
]
An organization’s profile, such as its city and description, is returned when the organization is retrieved, see Retrieve Organization Profile Information (v2).
Search Organizations (v2)¶
Use the search parameter to return only the organizations whose name or username (the org field) contains the search term. The match is partial and not case sensitive. Only organizations the requesting user has access to are searched.
GET /api/v2/orgs?search={term}
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.editordown toreadonly- 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 yourroleamong the organization’s members iseditor,managerorowner.memberandreadonly-no-download- every organization you belong to. This is the same as leavingroleout.
GET /api/v2/orgs?role={role}
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¶
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).
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"}.
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.
GET /api/v1/orgs/{username}/membersExample¶
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.
GET /api/v2/orgs/{username}/membersExample¶
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,readonlyorreadonly-no-download. Optional when adding a member. Required when updating a member, unless the member is being removed.remove- When updating a member,trueremoves the member from the organization.email_msgandemail_subject- An email with this message is sent to the member.email_subjectis 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.
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"}
POST /api/v1/orgs/{username}/membersExample¶
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.
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"}.
PUT /api/v1/orgs/{username}/membersExample¶
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"}.
DELETE /api/v1/orgs/{username}/membersExample¶
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¶
POST /api/v1/orgs/{username}/rotate-keyExample¶
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,
}