coss.comdocs

Add your own OAuth app

POST
/v1/scheduling/oauth_apps

New consents in this environment use it, so the consent screen shows your brand. Connections made before it stay on coss.com's app until their host consents again. On the Scale plan and above. Secrets 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"
client_id*string

The app's client ID at the provider.

Match^\S+$
Length1 <= length <= 500
client_secret*string

The app's client secret. Never returned.

Length1 <= length <= 1000
redirect_uri?string

A page on your own domain, registered with the provider, that forwards code and state to coss_callback_url. Google requires this for an external app, since it has to verify the redirect's domain as yours. Leave it out to use coss_callback_url directly.

Lengthlength <= 2000
completion_url?string

Where the browser lands after a consent that didn't name a return_url, with coss_calendar set to connected, denied or invalid. Leave it out for a plain page saying what happened.

Lengthlength <= 2000
secret_expires_at?string

When the client secret expires. Owners and admins are warned 14 days before.

Formatdate-time

Response Body

The app.

application/json
  1. response
object*"scheduling.oauth_app"
Value in"scheduling.oauth_app"
id*string
provider*string
Value in"google""microsoft""zoom"
client_id*string
tenant_id*string|null
redirect_uri*string|null
coss_callback_url*string

Register this with the provider if redirect_uri isn't set. If it is, that page forwards code and state here.

completion_url*string|null
zoom_event_url*|

Zoom only: the Event notification endpoint URL for your app's deauthorization events.

scopes*array<string>

What to enable on your app at the provider.

status*string

failing: the provider refused the app's credentials. New consents are refused, and calendars connected through it can't be read until they work again.

Value in"active""failing"
last_error_code*string|null
last_error_at*string|null
secret_expires_at*string|null
verified_at*|

When a consent first completed through this app, which proves its secret.

connections*integer

Calendar connections using this app. It can't be deleted while there are any.

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.oauthApps.create({  provider: "google",  client_id: "1234567890-abc.apps.googleusercontent.com",  client_secret: "GOCSPX-abcdefghijklmnopqrstuvwxyz",  redirect_uri: "https://example.com/oauth/google",  completion_url: "https://example.com/calendar-connected",});
{  "object": "scheduling.oauth_app",  "id": "calapp_01kd2m9a0b1c2d3e4f5g6h7j8m",  "provider": "google",  "client_id": "1234567890-abc.apps.googleusercontent.com",  "tenant_id": null,  "redirect_uri": "https://example.com/oauth/google",  "coss_callback_url": "https://api.coss.com/scheduling/oauth/google/callback",  "completion_url": "https://example.com/calendar-connected",  "zoom_event_url": null,  "scopes": [    "https://www.googleapis.com/auth/calendar.events.freebusy"  ],  "status": "active",  "last_error_code": null,  "last_error_at": null,  "secret_expires_at": null,  "verified_at": "2027-01-01T10:00:00.000Z",  "connections": 12,  "created_at": "2027-01-01T10:00:00.000Z",  "updated_at": "2027-01-01T10:00:00.000Z"}