Coda Admin API (0.0.2)

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 enterprise organizations. Only organization admins can use the Admin API for resources 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.

Coda's Admin 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.

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

Organizations

Enterprise customers have access to the Organization, an object that contains policy, rules, and audit events for a set of workspaces and one or more domains. Users accessing Coda via an Organization-registered domain are subject to that Organization's policies including allowed forms of authentication, doc & pack sharing restrictions, etc.

Workspaces

A workspace is your home base for all things Coda. It will store your docs in an organized way, and you'll invite members into the workspace to help you get the job done. A workspace can be free or paid (depending on your plan), and as the workspace's Doc Maker or Doc Maker (Admin), you'll be able to dictate the rules for how it works.

Learn more about Workspaces in our help center.

Folders

We use folders to keep docs organized in the workspace (think departments, teams, and projects). Your docs are where the true work gets done with all of your tables, text, and app-like solutions. Folders contain docs within the workspace.

Learn more about Folders in our help center.

Docs

Coda docs are foundational, top-level collaborative projects that contain pages.

Pack configurations

Pack configurations are the settings that define how a Pack may be used within an organization.

Pack configuration permissions

Pack configuration permissions are the settings that define which principals may use a Pack configuration.

Pack requests

When Pack configurations are turned on inside an organization. Pack requests are requests to use a Pack submitted by users in the organization.

Pages

Individual pages within a doc offer canvases containing rich text, tables, controls, and other objects.

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.

Entity Type	Action Name	Description
apiToken	DeleteApiToken	Delete an API token
apiToken	GenerateApiToken	Generate an API token
billingAccount	AddBillingGroup	Add a billing group to a billing account
billingAccount	AddBillingGroupAdmin	Assign a billing group admin
billingAccount	DeleteBillingGroup	Delete a billing group from a billing account
billingAccount	RemoveBillingGroupAdmin	Remove a billing group admin
billingAccount	UpdateBillingAccountSettings	Update settings for a billing account
brainQuery	BrainStructuredQuery	Query Coda Brain for structured data
brainQuery	BrainUnstructuredQuery	Query Coda Brain for unstructured data
doc	AddDocPack	Install a Pack within a 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	CopyTemplate	Copy template to an existing doc
doc	CreateDoc	Create a new doc
doc	DeleteAllReferencingSyncPageTunnels	Delete all sync page tunnels referencing a doc
doc	DeleteDoc	Delete a doc
doc	DeleteDocPack	Remove usage of a Pack from a doc
doc	EditDoc	Edit a doc
doc	ExportDocContent	Export doc content
doc	MoveDoc	Move a doc to a different folder
doc	OpenDoc	Opening a doc for reading, commenting or editing.
doc	ReviveDoc	Revive a deleted doc
doc	SubmitForm	Submit through a form
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	UpdateFolderPermissions	Update sharing permissions on a folder
folder	UpdateFolderSettings	Update folder settings
group	CreateGroup	Create a new group
group	DeleteGroup	Delete a group
group	UpdateGroup	Update group properties
ingestion	CreateIngestion	Create a new Coda Brain ingestion
ingestion	CreateIngestionPermissions	Create Coda Brain ingestion permissions
ingestion	DeleteIngestion	Delete a Coda Brain ingestion
ingestion	DeleteIngestionPermissions	Delete Coda Brain ingestion permissions
ingestion	UpdateIngestion	Update a Coda Brain ingestion
legalHold	CreateLegalHold	Create a new legal hold
legalHold	DeleteLegalHold	Delete a legal hold
legalHold	UpdateLegalHold	Update legal hold
legalHoldExport	CreateLegalHoldExport	Create a new legal hold export
legalHoldExport	DeleteLegalHoldExport	Delete a legal hold export
organization	ClaimDocOwnership	Claim ownership of a doc after the owner is deactivated
organization	OrganizationPackAccessRequested	A user requested access to a Pack
organization	TransferDocs	Transfer docs from one user to another
organization	UpdateOrganizationSettings	Update organization settings
organization	UpdateOrganizationUserActivation	Update a user's activation status in an organization
organization	UpdateOrganizationUserRole	Add or remove user from organization roles
pack	AddPackConfigurationPermission	Add a Pack configuration permission
pack	AllowPackAccessRequest	A user was granted access to a Pack
pack	CreatePack	Create a new Pack
pack	CreatePackConfiguration	Create a new Pack configuration
pack	DeleteAllConfigurationsOnPack	Delete all configurations for a Pack
pack	DeletePack	Delete a Pack
pack	DeletePackConfiguration	Delete a Pack configuration
pack	DeletePackConfigurationOAuth	Delete OAuth configuration metadata associated with a Pack configuration
pack	DenyPackAccessRequest	A user was denied access to a Pack
pack	RemovePackConfigurationPermission	Delete a Pack configuration permission
pack	SetPackConfigurationOAuth	Set OAuth configuration metadata associated with the Pack configuration
pack	SetPackConfigurationPermissions	Set permissions for a Pack configuration
pack	UpdatePackConfiguration	Update a Pack configuration
pack	UpdatePackPermissions	Update Pack permissions
packControl	SetPackControl	Set Pack control for an organization
syncPage	OpenSyncPage	Opening a sync page for reading.
syncPageTunnel	CreateSyncPageTunnel	Create a sync page tunnel
syncPageTunnel	DeleteSyncPageTunnel	Delete a sync page tunnel
syncPageTunnel	UpdateSyncPageTunnel	Update a sync page tunnel
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
webhook	CreateWebhook	Create a new webhook subscription
webhook	DeleteWebhook	Delete a webhook subscription
webhook	ResetWebhook	Resets a webhook subscription
webhook	UpdateWebhook	Updates parameters for an existing webhook subscription
workspace	CreateCustomIcon	Create a custom icon in a workspace
workspace	CreateWorkspace	Create a new workspace
workspace	DeleteCustomIcon	Delete a custom icon in a workspace
workspace	DeleteWorkspace	Delete a workspace
workspace	OffboardWorkspaceUser	Offboard a removed user from a workspace
workspace	PinDocToWorkspace	Pin a doc to a workspace
workspace	ReinstateWorkspaceUser	Allow a user to be re-added to a workspace
workspace	UnpinDocFromWorkspace	Unpin a doc from a workspace
workspace	UpdateWorkspaceSettings	Update workspace settings
workspace	UpdateWorkspaceUserBrainRole	Update a user's Brain role in a workspace
workspace	UpdateWorkspaceUserRole	Update a user's role in a workspace

More information

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

Webhooks enable an application to receive notifications of audit events in Coda as they occur.

Rather than having to "poll" repeatedly for new audit events, a webhook will "push" events to your internet-accessible endpoint via HTTP POST requests. This can be much more efficient and convenient for an internet-accessible service.

It is important to note that webhooks do require a server or server-like endpoint accesible on the internet at all times to receive these notifications. For simpler scenarios, it may be easier to just poll for audit events rather than host and maintain a server on the internet.

Webhook Considerations

This webhook implementation aims to deliver events within a few minutes of occurring under normal operating conditions.

The system will attempt retries when it detects failures, so it will be possible for you to receive the same events more than once depending on errors or timeouts occurring in your server or in the network infrastructure between Coda and your server. Once delivered successfully, it is not possible to replay webhook notifications.

Targets are expected to respond within 10 seconds before delivery times out and is considered a failure.

Failures are retried using exponential backoff timing; after 8 hours of consecutive failures, Coda will give up and place the webhook into a disabled state.

Webhook Setup

Once a new webhook connection is established, an initial handshake will be attempted in order to prove that the target is available on the internet and is owned by the registering entity. In addition, any time the webhook is updated to point to a new target URL, the handshake procedure will be kicked off.

After the initial handshake completes successfully, new audit events will immediately begin to flow to the target.

In the event that the handshake fails, the reset API can be used to force the webhook to retry the handshake process.

Webhook Handshake details

To prove that the target URL is available on the internet and is a valid webhook target, a handshake process is started anytime a new target URL is set on on a webhook. This process is asynchronous to the webhook setup API call.

Coda will send a HTTP GET request to the registered target URL with a HTTP header named X-Webhook-Code. The target must respond with a standard 200 or 204 HTTP response code and echo back the same header key and its value.

Webhook Payload details

Once the webhook handshake has completed successfully, Coda will send batches of audit events to the target URL using HTTP POST requests.

Each notifications the target receives will include:

• A X-Webhook-Signature header which enables the server to verify the payload is genuine and originated from Coda. This code is a SHA-256 HMAC of the stringified body of the POST request using the Coda-generated secret key available on the webhook object.
• A JSON body with key events which contains an array of audit events using the same format as returned by the listEvents endpoint detailed below.

Payload verification

Sample javascript code fragment for verifying a webhook payload originated from Coda:

const crypto = require('crypto');

// This field is available on the Coda webhook object.
const signatureKey = 'some value';

// These come from the webhook `POST` request to your server
const headers = {'X-Webhook-Signature': 'abc123'};
const body = {events: []};

const calculatedSignature = crypto
  .createHmac('SHA256', signatureKey)
  .update(JSON.stringify(body))
  .digest("hex");

const isValidSignature = crypto.timingSafeEqual(
  Buffer.from(calculatedSignature),
  Buffer.from(headers['X-Webhook-Signature']),
);

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.

The Coda Admin API sets a reasonable limit on the number of requests that can be made per minute. Once this limit is reached, calls to the API will start returning errors with an HTTP status code of 429.

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

• OpenAPI 3.0 spec - YAML
• OpenAPI 3.0 spec - JSON

View and revoke individual user API tokens within an organization.

Coda docs are foundational, top-level collaborative projects that contain pages. The API lets you list and search your docs.

This API lets you manage sharing and permissions for your docs.

Export docs for backup or ingestion into a DLP or eDiscovery system.