The Coda Admin API is a RESTful API that allows programmatic access to administrative reports & capabilities within Coda.
Access to the Admin API is limited to approved enterprise organizations. To gain access, please email help+admin-api@coda.io. Only admins of an organization can use the Admin API to list audit events related to their organization.
As we update and release newer versions of the API, we reserve the right to remove older APIs and functionality with a 3-month deprecation notice. We will post about such changes as well as announce new features in the Developers Central section of our Community, and update the API updates doc.
Audit events contain records of user login/logout activities and other operations performed within a Coda organization. Audit events are critical to an enterprise’s Security Monitoring efforts. It enables Security professionals to proactively analyze the audit events for any suspicious behavior within a Coda organization and help them in forensic investigations in case of a security breach. Audit events also enable administrators to write their own applications to understand their users’ usage of Coda.
The following entity types and actions are audited and can be used to filter results using the entityType
and action
query parameters.
Entity Type | Action Name | Description |
---|---|---|
apiToken |
DeleteApiToken |
Delete an API token |
apiToken |
GenerateApiToken |
Generate an API token |
doc |
AddDocPack |
Install a Pack within a doc |
doc |
CreateDoc |
Create a new doc |
doc |
CopyDoc |
Copy a doc to a new location |
doc |
CopyPages |
Copy pages and sub pages within a doc to a new location |
doc |
DeleteDoc |
Delete a doc |
doc |
DeleteDocPack |
Remove usage of a Pack from a doc |
doc |
OpenDoc |
Opening a doc for reading, commenting or editing. |
doc |
ReviveDoc |
Revive a deleted doc |
doc |
UpdateDocPermissions |
Update sharing permissions on a doc |
folder |
CreateFolder |
Create a new folder |
folder |
DeleteFolder |
Delete a folder |
folder |
UpdateFolderMembership |
Update membership on a folder |
folder |
UpdateFolderSettings |
Update folder settings |
workspace |
UpdateWorkspaceSettings |
Update workspace settings |
workspace |
UpdateWorkspaceUserRole |
Update a user's role in a workspace |
workspace |
OffboardWorkspaceUser |
Offboard a removed user from a workspace |
workspace |
ReinstateWorkspaceUser |
Allow a user to be re-added to a workspace |
organization |
UpdateOrganizationPackAccess |
Enable or disable usage of a Pack within an organization |
organization |
UpdateOrganizationSettings |
Update organization settings |
organization |
UpdateOrganizationUserRole |
Add or remove user from organization roles |
pack |
CreatePack |
Create a new Pack |
user |
CreateUser |
Create a new user |
user |
DeleteUser |
Delete an existing user |
user |
LogInUser |
Login activity of a user |
user |
LogOutUser |
Logout activity of a user |
user |
ResetUserPassword |
Reset a user's password |
user |
UpdateUserAccount |
Update a user's account details |
user |
UpdateUserPassword |
Update a user's password |
For more information about the Coda Admin API and these events, detailed information and examples are available.
Endpoints supporting listing of resources have the following fields:
items
: An array containing the listed resources, limited by the limit
or pageToken
query parametersnextPageLink
: If more results are available, an API link to the next page of resultsnextPageToken
: If more results are available, a page token that can be passed into the pageToken
query parameterThe maximum page size may change at any time, and may be different for different endpoints. Please do not rely on it
for any behavior of your application. If you pass a limit
parameter that is larger than our maximum allowed limit,
we will only return as many results as our maximum limit. You should look for the presence of the nextPageToken
on the
response to see if there are more results available, rather than relying on a result set that matches your provided limit.
To fetch a subsequent page of results, pass the pageToken
parameter. Set this parameter to the value given to you as the nextPageToken
in a page response. If no value is provided, there are no more results available. You only need to pass the pageToken
to get
the next page of results, you don't need to pass any of the parameters from your original request, as they are all
implied by the pageToken
. Any other parameters provided alongside a pageToken
will be ignored.
In an effort to standardize our API and make it accessible, we offer an OpenAPI 3.0 specification:
The Coda API can be accessed using an API token, which can be obtained from My account in Coda. This token should be specified by setting a header as follows.
Authorization: Bearer <api_token>
Keep your token safe, as anyone who gets access to it can access your account. Once a token is created it cannot be viewed or modified, so don't lose it.
If you're logged into Coda, you can also query the API directly using your browser. Note that only GET endpoints are supported; for anything else, you'll have to use Bearer authentication.
Security Scheme Type | HTTP |
---|---|
HTTP Authorization Scheme | bearer |
Bearer format | "UUID" |
Returns a list of audit events within an organization. Audit events will be returned in descending time order from newest to oldest.
organizationId required | string Example: org-AbCDeFGHIj ID of the organization. |
startTime | integer Return audit events created on or after the given Unix timestamp. |
endTime | integer Return audit events created on or before the given Unix timestamp. |
action | string Name of the action performed. |
userId | number The Coda ID of the user who initiated the action. |
string The email address of the user who initiated the action. | |
entityType | string (Type) Enum: "apiToken" "doc" "docPackConnection" "event" "folder" "organization" "pack" "user" "workspace" Target entity type of the action. |
entityId | string Target entity ID of the action. Requires |
containerWorkspaceId | string Workspace ID that contained the entity at the time the event was generated. |
containerFolderId | string Folder ID that contained the entity at the time the event was generated. |
limit | integer [ 1 .. 500 ] Default: 100 Example: limit=10 Maximum number of results to return in this query. |
pageToken | string Example: pageToken=eyJsaW1pd An opaque token used to fetch the next page of results. |
import requests headers = {'Authorization': 'Bearer <your API token>'} uri = 'https://coda.io/apis/admin/v1/organizations/<your organization id>/events' params = { 'action': 'docAccessDenied', } res = requests.get(uri, headers=headers, params=params).json() print(f'First event is: {res["items"][0]["action"]}') # => TODO: add response
{- "items": [
- {
- "timestamp": 1614175261,
- "user": {
- "type": "user",
- "id": 867102,
- "email": "user@example.com"
}, - "userContext": {
- "source": "browser",
- "sessionId": "as-zxfl5qXkN2",
- "browser": {
- "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36",
- "ipAddress": "192.0.2.0"
}
}, - "action": "docAccessDenied",
- "entity": {
- "type": "doc",
- "apiToken": {
- "type": "apiToken",
- "id": "AbCDeFGH",
- "name": "Cool Coda Integration"
}, - "doc": {
- "type": "doc",
- "id": "AbCDeFGH",
- "name": "Product Launch Hub",
- "href": "https://coda.io/apis/admin/v1/docs/AbCDeFGH",
- "browserLink": "https://coda.io/d/_dAbCDeFGH"
}, - "folder": {
- "type": "folder",
- "id": "fl-1Ab234",
- "name": "My docs"
}, - "organization": {
- "type": "organization",
- "id": "org-1AbcdeFgh1",
- "name": "Coda"
}, - "pack": {
- "type": "pack",
- "id": 1003,
- "name": "Cool Geometry Formulas"
}, - "user": {
- "type": "user",
- "id": 867102,
- "email": "user@example.com"
}, - "workspace": {
- "type": "workspace",
- "id": "ws-1Ab234",
- "name": "coda.io"
}
}, - "eventDetails": { },
- "result": "Success",
- "organizationId": "org-1AbcdeFgh1"
}
], - "href": "https://coda.io/apis/admin/v1/organizations/org-1AbcdeFgh1/audit/events?limit=20",
- "nextPageToken": "eyJsaW1pd",
- "nextPageLink": "https://coda.io/apis/admin/v1/organizations/org-1AbcdeFgh1/audit/events?pageToken=eyJsaW1pd"
}
Returns a list of users within an organization, across all registered domains.
organizationId required | string Example: org-AbCDeFGHIj ID of the organization. |
limit | integer [ 1 .. 500 ] Default: 100 Example: limit=10 Maximum number of results to return in this query. |
pageToken | string Example: pageToken=eyJsaW1pd An opaque token used to fetch the next page of results. |
import requests headers = {'Authorization': 'Bearer <your API token>'} uri = 'https://coda.io/apis/admin/v1/organizations/<your organization id>/users' res = requests.get(uri, headers=headers, params=params).json() print(f'First user is: {res["items"][0]["email"]}')
{- "items": [
- {
- "id": 12345,
- "email": "hello@coda.io",
- "name": "Sally Jane",
- "status": "Active",
- "registeredAt": "2018-04-11T00:18:57.946Z"
}
], - "href": "https://coda.io/apis/admin/v1/organizations/org-1AbcdeFgh1/users?limit=20",
- "nextPageToken": "eyJsaW1pd",
- "nextPageLink": "https://coda.io/apis/admin/v1/organizations/org-1AbcdeFgh1/users?pageToken=eyJsaW1pd"
}
Transfers resources such as docs and workspace membership from a deactivated user to an active user.
organizationId required | string Example: org-AbCDeFGHIj ID of the organization. |
Parameters for the resource transfer.
fromEmail required | string The email address of the user to transfer resources away from. |
toEmail required | string The email address of the user to transfer resources to. |
{- "fromEmail": "joe@example.com",
- "toEmail": "april@example.com"
}
{- "requestId": "c5cb3278-800e-4ae3-be53-19b0b794f8e1"
}
Activates a deactivated user.
organizationId required | string Example: org-AbCDeFGHIj ID of the organization. |
userEmail required | string <email> Example: april@example.com User to act upon. |
import requests headers = {'Authorization': 'Bearer <your API token>'} uri = 'https://coda.io/apis/admin/v1/organizations/<your organization id>/users/<user email>/activate' res = requests.get(uri, headers=headers, params=params).json() print(f'Successully activated!')
{ }
Deactivates a user, ensuring the user is no longer paid and allowing their docs to be reassigned to a new owner.
organizationId required | string Example: org-AbCDeFGHIj ID of the organization. |
userEmail required | string <email> Example: april@example.com User to act upon. |
import requests headers = {'Authorization': 'Bearer <your API token>'} uri = 'https://coda.io/apis/admin/v1/organizations/<your organization id>/users/<user email>/deactivate' res = requests.get(uri, headers=headers, params=params).json() print(f'Successully deactivated!')
{ }