Start calendar OAuth — Calendar

Begin a human Google/Microsoft calendar authorization.

Action: app_topolo_calendar.external_calendars.oauth.start · POST /api/admin/external-calendars/oauth/start

Declared permission: app_topolo_calendar.availability:write. For authorized Calendar users; permissions and resource access still apply.

Before you start

Use the current credential to confirm the production organization and inspect this exact action before preparing a call.
Declared permission: app_topolo_calendar.availability:write. Permission discovery is not a grant.
Discover the authorized Calendar workspace and pass it as resourceType=workspace/resourceId separately from this action input. Calendar records and IDs are scoped to the selected host/workspace.
Validate and plan the exact payload, obtain effect-specific authorization, then execute unchanged only in a separately authorized operational task. Do not run these synthetic inputs.

Inputs and field meanings

Field	Presence	Declared constraint	Meaning
`provider`	required	string; enum=["google", "microsoft"]	Declared provider: create supports manual/ics, OAuth start google/microsoft. Use the action-specific enum.
`redirectPath`	optional	string	Post-consent app path. The reviewed OAuth-start route accepts a path beginning /app and otherwise defaults to /app/availability.

Worked request and response

Source-reviewed illustration only. Nothing below was executed; all identifiers, counts, states, credentials and URLs are synthetic. Replace identifiers through discovery before any separately authorized call.

Resource context: workspace; it is not an extra action input field.

Illustrative action input:

{
  "provider": "google",
  "redirectPath": "/app/availability"
}

Illustrative HTTP 200 source response:

{
  "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=illustrative-only&state=illustrative-only"
}

authorizationUrl is a synthetic shape illustration, not a usable authorization flow or captured state. A person must complete the actual returned URL. No connection or sync is established by this start response.

The illustrative response passes the declared structural schema. This establishes only schema compatibility, not deployed shape, values, authorization or business outcome.

Effects and verification

Creates a temporary OAuth state and returns a provider consent URL; no connection is completed yet.

After actual human consent, read external_calendars.list and separately verify sync; preserve incomplete consent as incomplete.

Refusals and recovery

Selected source refusals are listed below; runtime middleware can return additional structured errors.

HTTP	Error	Supported response
403	`forbidden`	Reconcile the declared permission, organization and verified resource grant with the legitimate access owner; do not switch context to bypass a refusal.
404	`no_host`	Read host.get; if it returns host:null, create the intended workspace host through host.update before retrying.
400	`invalid_provider`	Use google or microsoft.
503	`google_calendar_oauth_not_configured`	The operator must qualify the provider configuration; do not substitute credentials or another environment.

Recovery: No cancellation action for the temporary OAuth state is published here. Do not complete an unintended flow; a completed connection requires explicit owner-directed disconnect through its real connection record.

After an uncertain mutation, reconcile the named records and provider/delivery evidence before repeating it.

app_topolo_calendar.host.get: Read the selected workspace host, including the unconfigured host:null state.
app_topolo_calendar.external_calendars.list: Discover external calendar IDs, connection state and sync history.
app_topolo_calendar.external_calendars.sync: Replace an external calendar’s imported busy-time snapshot.

Declared schemas and provenance

The hidden action guide carries these exact current declared schemas. They are not rewritten to make the illustrations pass.

Input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "google",
        "microsoft"
      ]
    },
    "redirectPath": {
      "type": "string"
    }
  },
  "required": [
    "provider"
  ],
  "additionalProperties": false
}

Output schema:

{
  "type": "object",
  "title": "Start calendar OAuth response",
  "description": "Operation result returned by external_calendars.oauth.start.",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "id": {
      "type": "string"
    },
    "data": {
      "oneOf": [
        {
          "type": "object",
          "title": "external record",
          "properties": {
            "id": {
              "type": "string",
              "description": "Stable identifier when the external exposes one."
            }
          },
          "additionalProperties": true
        },
        {
          "type": "object",
          "additionalProperties": true
        }
      ]
    },
    "result": {
      "type": "object",
      "additionalProperties": true
    },
    "message": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "x-topolo-contract-source": "derived-action-metadata",
  "x-topolo-contract-precision": "structural"
}

Source: TopoloCalendar@b378ceb73800ee1d1e6c4ff6f0b4179918cf632c, apps/api/src/routes/admin-external-calendars.ts. Current catalog metadata and source were compared without executing the application.

Source-reviewed synthetic input/response; not captured or executed.
Source revision is not proof of current deployment, caller access, provider connection or notification delivery.
The illustrative response passes the declared structural schema. This establishes only schema compatibility, not deployed shape, values, authorization or business outcome.
redirectPath is honored only when it starts with /app; the reviewed route otherwise uses /app/availability.