Coda Admin API (0.0.1)

Admin API Support: help+admin-api@coda.io URL: https://coda.io Terms of Service

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:

Bearer

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

Python 3.7
Shell

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": [{"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"
}

Users

List organization users

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

Authorizations:

Bearer

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

Python 3.7
Shell

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": [{"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"
}

Transfer user resources

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

Authorizations:

Bearer

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

Payload
Python 3.7

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:

Bearer

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

Python 3.7
Shell

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:

Bearer

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

Python 3.7
Shell

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

{ }