Coda Admin API (0.0.1)

Introduction

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.

Using the Admin API

Coda's REST API is designed to be straightforward to use. You can use the language and platform of your choice to make requests. To get a feel for the API, you can also use a tool like Postman or Insomnia.

API Endpoint

This API uses a base path of https://coda.io/apis/admin/v1.

Audit events

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.

Audit event actions

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

More information

For more information about the Coda Admin API and these events, detailed information and examples are available.

List Endpoints

Endpoints supporting listing of resources have the following fields:

  • items: An array containing the listed resources, limited by the limit or pageToken query parameters
  • nextPageLink: If more results are available, an API link to the next page of results
  • nextPageToken: If more results are available, a page token that can be passed into the pageToken query parameter

The 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.

OpenAPI/Swagger Spec

In an effort to standardize our API and make it accessible, we offer an OpenAPI 3.0 specification:

Authentication

Bearer

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"

Events

Provides access to audit events within an organization.

List audit events

Returns a list of audit events within an organization. Audit events will be returned in descending time order from newest to oldest.

Authorizations:
path Parameters
organizationId
required
string
Example: org-AbCDeFGHIj

ID of the organization.

query Parameters
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.

email
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 entityType to be present.

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.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "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"
}

Users

List organization users

Returns a list of users within an organization, across all registered domains.

Authorizations:
path Parameters
organizationId
required
string
Example: org-AbCDeFGHIj

ID of the organization.

query Parameters
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.

Responses

Request samples

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"]}')

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "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"
}

Transfer user resources

Transfers resources such as docs and workspace membership from a deactivated user to an active user.

Authorizations:
path Parameters
organizationId
required
string
Example: org-AbCDeFGHIj

ID of the organization.

Request Body schema: application/json

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.

Responses

Request samples

Content type
application/json
{
  • "fromEmail": "joe@example.com",
  • "toEmail": "april@example.com"
}

Response samples

Content type
application/json
{
  • "requestId": "c5cb3278-800e-4ae3-be53-19b0b794f8e1"
}

Activate a user

Activates a deactivated user.

Authorizations:
path Parameters
organizationId
required
string
Example: org-AbCDeFGHIj

ID of the organization.

userEmail
required
string <email>
Example: april@example.com

User to act upon.

Responses

Request samples

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!')

Response samples

Content type
application/json
{ }

Deactivate a user

Deactivates a user, ensuring the user is no longer paid and allowing their docs to be reassigned to a new owner.

Authorizations:
path Parameters
organizationId
required
string
Example: org-AbCDeFGHIj

ID of the organization.

userEmail
required
string <email>
Example: april@example.com

User to act upon.

Responses

Request samples

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!')

Response samples

Content type
application/json
{ }