coss.comdocs

Add a calendar delegation

POST
/v1/scheduling/calendar_delegations

An admin authorizes once, and every host on the domain gets their calendar with no consent screen. It stays pending: authorize what it returns, then verify it. Credentials are never returned.

Authorization

bearerAuth
headerAuthorizationBearer <token>

A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.

Header Parameters

Coss-Version?"2026-10-10"

The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.

Value in"2026-10-10"

Request Body

application/json
  1. body
provider*"google"
Value in"google"
domain*string

The Workspace or Microsoft 365 domain. Only addresses on exactly this domain connect, not its subdomains.

Match^[a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+)+$
Lengthlength <= 253
match_host_email?boolean

Whether a host's email picks their mailbox when calendar_account isn't set. Turn it off if end users can type their own email into your app: otherwise one could name a colleague's address and reach that calendar.

service_account_key*string

The whole JSON key of a service account in your Google Cloud project. Never returned.

Lengthlength <= 10000

Response Body

The delegation.

application/json
  1. response
object*"scheduling.calendar_delegation"
Value in"scheduling.calendar_delegation"
id*string
provider*string
Value in"google""microsoft"
domain*string
status*string

pending: not verified yet. failing: the provider refused access, and its hosts aren't offered until it's back. deleting: its connections are being removed.

Value in"pending""active""failing""deleting"
match_host_email*boolean
client_id*string

Google: the numeric client ID your Workspace admin authorizes.

tenant_id*string|null
scopes*array<string>

What to authorize: OAuth scopes in Google's Admin console, the application permission in Entra.

verified_account*string|null
last_error_code*string|null
failing_since*string|null
secret_expires_at*string|null
hosts_connected*integer
hosts_failed*integer

Hosts whose mailbox can't be reached, or who are out while this is failing.

created_at*string
updated_at*string
import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.scheduling.calendarDelegations.create({  provider: "microsoft",  domain: "example.com",  tenant_id: "7d3f1c52-8e0b-4d6e-9a27-5c4b1e7d2f60",  client_id: "3f1c7a52-8e0b-4d6e-9a27-5c4b1e7d2f60",  client_secret: "abc~defghijklmnopqrstuvwxyz",});
{  "object": "scheduling.calendar_delegation",  "id": "caldlg_01kd2m9a0b1c2d3e4f5g6h7j8m",  "provider": "google",  "domain": "example.com",  "status": "active",  "match_host_email": true,  "client_id": "117063284751902345678",  "tenant_id": null,  "scopes": [    "https://www.googleapis.com/auth/calendar.events.freebusy"  ],  "verified_account": "ana@example.com",  "last_error_code": null,  "failing_since": null,  "secret_expires_at": null,  "hosts_connected": 240,  "hosts_failed": 1,  "created_at": "2027-01-01T10:00:00.000Z",  "updated_at": "2027-01-01T10:00:00.000Z"}