Integrations

/api/v1 operations for integrations. See HTTP API for authentication, the error envelope, and rate limits.

Operations

GET /api/v1/integrations

List integrations

Returns the organization's connected mailbox integrations (first-party, org-owned). Responses never include token material; use the token endpoint to mint an access token.

Auth: API key required.

Operation ID: listIntegrations

Responses:

• 200 — The organization's integrations.
• 401 — Authentication is missing or invalid.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan integrations list

POST /api/v1/integrations

Start connecting an integration

Begins a Gmail (google) or Outlook (microsoft) mailbox connection and returns a connect URL. The provider defaults to google. OAuth consent happens in a browser, so a human must open the returned URL to authorize; the connection appears in the list once approved. Returns 503 provider_not_configured when the requested provider is not configured in this environment.

Auth: API key required.

Operation ID: connectIntegration

Request body (application/json, required):

• provider ("google" | "microsoft", optional)

Responses:

• 200 — A connect URL for the requested provider.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.
• 503 — Response.

CLI: khotan integrations connect

GET /api/v1/integrations/{integrationId}

Get an integration

Returns one connected mailbox integration. Responses never include token material.

Auth: API key required.

Operation ID: getIntegration

Path parameters:

• integrationId (string, required)

Responses:

• 200 — The integration.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan integrations get

PATCH /api/v1/integrations/{integrationId}

Update an integration

Updates an integration's display name. Pass null to clear it. Tokens and the mailbox are fixed by OAuth and cannot be changed.

Auth: API key required.

Operation ID: updateIntegration

Path parameters:

• integrationId (string, required)

Request body (application/json, required):

• name (string | null, required)

Responses:

• 200 — The updated integration.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan integrations rename

DELETE /api/v1/integrations/{integrationId}

Disconnect an integration

Disconnects a mailbox: the stored credentials are revoked and the connection stops driving sync. This is permanent; reconnecting requires a fresh OAuth consent.

Auth: API key required.

Operation ID: deleteIntegration

Path parameters:

• integrationId (string, required)

Responses:

• 200 — The integration was disconnected.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan integrations delete

POST /api/v1/integrations/{integrationId}/token

Mint an access token (secret)

Mints a fresh, short-lived OAuth access token for a Gmail or Outlook integration using its stored refresh token, and returns it with its expiry and scopes. The token grants access to the connected mailbox; treat it as a secret. Returns 409 connection_unusable if the grant was revoked at the provider, and 503 provider_not_configured if the integration's provider is not configured in this environment.

Auth: API key required.

Operation ID: mintIntegrationToken

Path parameters:

• integrationId (string, required)

Responses:

• 200 — A freshly-minted access token. Secret-bearing.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.
• 503 — Response.

CLI: khotan integrations token