openapi: 3.2.0 info: title: Cal.com API v2 Orgs / Delegation Credentials API description: '' version: 1.0.0 contact: {} servers: [] tags: - name: Orgs / Delegation Credentials paths: /v2/organizations/{orgId}/delegation-credentials: get: description: 'Optionally filter by `domain` to look up the delegation credential configured for a specific domain. Required membership role: `org admin`. PBAC permission: `organization.readDelegationCredentials`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control' operationId: OrganizationsDelegationCredentialController_getDelegationCredentials parameters: - name: Authorization in: header description: For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_ required: false schema: type: string - name: x-cal-secret-key in: header description: For platform customers - OAuth client secret key required: false schema: type: string - name: x-cal-client-id in: header description: For platform customers - OAuth client ID required: false schema: type: string - name: orgId required: true in: path description: The unique identifier of the organization whose delegation credentials are returned schema: example: 123 type: number - name: take required: false in: query description: Maximum number of items to return schema: minimum: 1 maximum: 250 default: 250 example: 25 type: number - name: skip required: false in: query description: Number of items to skip schema: minimum: 0 default: 0 example: 0 type: number - name: domain required: false in: query description: Filter by the domain the delegation credential is configured for schema: example: example.com type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/GetDelegationCredentialsOutput' '401': description: Authentication is missing or invalid content: application/json: schema: type: object properties: status: type: string example: error timestamp: type: string example: '2024-04-01T00:00:00.000Z' path: type: string example: /v2/organizations/123/delegation-credentials error: type: object properties: code: type: string example: UnauthorizedException message: type: string '403': description: The authenticated user is not an org admin, lacks the `organization.read` permission, or the organization is not on the required plan content: application/json: schema: type: object properties: status: type: string example: error timestamp: type: string example: '2024-04-01T00:00:00.000Z' path: type: string example: /v2/organizations/123/delegation-credentials error: type: object properties: code: type: string example: ForbiddenException message: type: string summary: Get all delegation credentials of your organization tags: - Orgs / Delegation Credentials x-platform-plan: SCALE post: description: 'Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control' operationId: OrganizationsDelegationCredentialController_createDelegationCredential parameters: - name: Authorization in: header description: For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_ required: false schema: type: string - name: x-cal-secret-key in: header description: For platform customers - OAuth client secret key required: false schema: type: string - name: x-cal-client-id in: header description: For platform customers - OAuth client ID required: false schema: type: string - name: orgId required: true in: path schema: type: number requestBody: required: true content: application/json: schema: anyOf: - $ref: '#/components/schemas/CreateGoogleDelegationCredentialInput' - $ref: '#/components/schemas/CreateMicrosoftDelegationCredentialInput' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/CreateDelegationCredentialOutput' summary: Save delegation credentials for your organization tags: - Orgs / Delegation Credentials x-platform-plan: SCALE /v2/organizations/{orgId}/delegation-credentials/{credentialId}: get: description: 'Required membership role: `org admin`. PBAC permission: `organization.readDelegationCredentials`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control' operationId: OrganizationsDelegationCredentialController_getDelegationCredential parameters: - name: Authorization in: header description: For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_ required: false schema: type: string - name: x-cal-secret-key in: header description: For platform customers - OAuth client secret key required: false schema: type: string - name: x-cal-client-id in: header description: For platform customers - OAuth client ID required: false schema: type: string - name: orgId required: true in: path description: The unique identifier of the organization the delegation credential belongs to schema: example: 123 type: number - name: credentialId required: true in: path description: The unique identifier of the delegation credential schema: example: clsx1234567890 type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/GetDelegationCredentialOutput' '401': description: Authentication is missing or invalid content: application/json: schema: type: object properties: status: type: string example: error timestamp: type: string example: '2024-04-01T00:00:00.000Z' path: type: string example: /v2/organizations/123/delegation-credentials/clsx1234567890 error: type: object properties: code: type: string example: UnauthorizedException message: type: string '403': description: The authenticated user is not an org admin, lacks the `organization.read` permission, or the organization is not on the required plan content: application/json: schema: type: object properties: status: type: string example: error timestamp: type: string example: '2024-04-01T00:00:00.000Z' path: type: string example: /v2/organizations/123/delegation-credentials/clsx1234567890 error: type: object properties: code: type: string example: ForbiddenException message: type: string '404': description: No delegation credential with the given id exists in the organization, or it belongs to a different organization content: application/json: schema: type: object properties: status: type: string example: error timestamp: type: string example: '2024-04-01T00:00:00.000Z' path: type: string example: /v2/organizations/123/delegation-credentials/clsx1234567890 error: type: object properties: code: type: string example: NotFoundException message: type: string summary: Get a delegation credential of your organization tags: - Orgs / Delegation Credentials x-platform-plan: SCALE patch: description: 'Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control' operationId: OrganizationsDelegationCredentialController_updateDelegationCredential parameters: - name: Authorization in: header description: For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_ required: false schema: type: string - name: x-cal-secret-key in: header description: For platform customers - OAuth client secret key required: false schema: type: string - name: x-cal-client-id in: header description: For platform customers - OAuth client ID required: false schema: type: string - name: orgId required: true in: path schema: type: number - name: credentialId required: true in: path schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateDelegationCredentialInput' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/UpdateDelegationCredentialOutput' summary: Update delegation credentials of your organization tags: - Orgs / Delegation Credentials x-platform-plan: SCALE delete: description: 'Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control' operationId: OrganizationsDelegationCredentialController_deleteDelegationCredential parameters: - name: Authorization in: header description: For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_ required: false schema: type: string - name: x-cal-secret-key in: header description: For platform customers - OAuth client secret key required: false schema: type: string - name: x-cal-client-id in: header description: For platform customers - OAuth client ID required: false schema: type: string - name: orgId required: true in: path schema: type: number - name: credentialId required: true in: path schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/DeleteDelegationCredentialOutput' summary: Delete delegation credentials of your organization tags: - Orgs / Delegation Credentials x-platform-plan: SCALE /v2/organizations/{orgId}/delegation-credentials/{credentialId}/reset-rotation: post: description: 'Clears the terminal secret-rotation failure state so managed secret rotation resumes normally. Use this after fixing whatever external configuration issues caused rotation to reach a terminal state. Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control' operationId: OrganizationsDelegationCredentialController_resetDelegationCredentialRotation parameters: - name: Authorization in: header description: For non-platform customers - value must be `Bearer ` where `` is api key prefixed with cal_ required: false schema: type: string - name: x-cal-secret-key in: header description: For platform customers - OAuth client secret key required: false schema: type: string - name: x-cal-client-id in: header description: For platform customers - OAuth client ID required: false schema: type: string - name: orgId required: true in: path description: The unique identifier of the organization the delegation credential belongs to schema: example: 123 type: number - name: credentialId required: true in: path description: The unique identifier of the delegation credential schema: example: clsx1234567890 type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ResetDelegationCredentialRotationOutput' '400': description: The delegation credential is not a Microsoft/office365 delegation credential content: application/json: schema: type: object properties: status: type: string example: error timestamp: type: string example: '2024-04-01T00:00:00.000Z' path: type: string example: /v2/organizations/123/delegation-credentials/clsx1234567890/reset-rotation error: type: object properties: code: type: string example: BadRequestException message: type: string '401': description: Authentication is missing or invalid content: application/json: schema: type: object properties: status: type: string example: error timestamp: type: string example: '2024-04-01T00:00:00.000Z' path: type: string example: /v2/organizations/123/delegation-credentials/clsx1234567890/reset-rotation error: type: object properties: code: type: string example: UnauthorizedException message: type: string '403': description: The authenticated user is not an org admin, lacks the `organization.update` permission, or the organization is not on the required plan content: application/json: schema: type: object properties: status: type: string example: error timestamp: type: string example: '2024-04-01T00:00:00.000Z' path: type: string example: /v2/organizations/123/delegation-credentials/clsx1234567890/reset-rotation error: type: object properties: code: type: string example: ForbiddenException message: type: string '404': description: No delegation credential with the given id exists in the organization, or it belongs to a different organization content: application/json: schema: type: object properties: status: type: string example: error timestamp: type: string example: '2024-04-01T00:00:00.000Z' path: type: string example: /v2/organizations/123/delegation-credentials/clsx1234567890/reset-rotation error: type: object properties: code: type: string example: NotFoundException message: type: string summary: Reset a blocked delegation credential's secret rotation state tags: - Orgs / Delegation Credentials x-platform-plan: SCALE components: schemas: DelegationCredentialWithClientIdOutput: type: object properties: id: type: string description: The unique identifier of the delegation credential example: clsx1234567890 enabled: type: boolean description: Whether the delegation credential is currently enabled example: true domain: type: string description: The email domain the delegation credential applies to example: example.com organizationId: type: number description: The unique identifier of the organization the delegation credential belongs to example: 123 workspacePlatform: $ref: '#/components/schemas/WorkspacePlatformDto' createdAt: format: date-time type: string description: The date and time when the delegation credential was created example: '2024-04-01T00:00:00.000Z' updatedAt: format: date-time type: string description: The date and time when the delegation credential was last updated example: '2024-04-01T00:00:00.000Z' serviceAccountClientId: type: - string - 'null' description: The client id of the service account associated with the delegation credential. The service account's private key is never returned. example: '1234567890' required: - id - enabled - domain - organizationId - workspacePlatform - createdAt - updatedAt - serviceAccountClientId WorkspacePlatformDto: type: object properties: name: type: string description: The name of the workspace platform the delegation credential is configured for example: Google slug: type: string description: The slug of the workspace platform the delegation credential is configured for example: google required: - name - slug DeleteDelegationCredentialOutput: type: object properties: status: enum: - success - error type: string example: success data: oneOf: - title: Google Service Account $ref: '#/components/schemas/GoogleDelegationCredentialOutput' - title: Microsoft Service Account $ref: '#/components/schemas/MicrosoftDelegationCredentialOutput' required: - status - data GetDelegationCredentialsOutput: type: object properties: status: enum: - success - error type: string example: success description: The status of the request, either `success` or `error` data: type: array items: oneOf: - title: Google Service Account $ref: '#/components/schemas/GoogleDelegationCredentialWithClientIdOutput' - title: Microsoft Service Account $ref: '#/components/schemas/MicrosoftDelegationCredentialWithClientIdOutput' - title: Delegation Credential $ref: '#/components/schemas/DelegationCredentialWithClientIdOutput' description: The list of delegation credentials belonging to the organization required: - status - data ResetDelegationCredentialRotationOutput: type: object properties: status: enum: - success - error type: string example: success data: oneOf: - title: Microsoft Service Account $ref: '#/components/schemas/MicrosoftDelegationCredentialOutput' allOf: - $ref: '#/components/schemas/MicrosoftDelegationCredentialOutput' required: - status - data CreateGoogleDelegationCredentialInput: type: object properties: domain: type: string workspacePlatformSlug: type: string enum: - google serviceAccountKey: $ref: '#/components/schemas/GoogleServiceAccountKeyInput' required: - domain - workspacePlatformSlug - serviceAccountKey UpdateDelegationCredentialInput: type: object properties: enabled: type: boolean serviceAccountKey: type: array items: oneOf: - title: Google Service Account $ref: '#/components/schemas/GoogleServiceAccountKeyInput' - title: Microsoft Service Account $ref: '#/components/schemas/MicrosoftServiceAccountKeyInput' optOutAutoSecretRotation: type: boolean description: When true, Cal.com will not mint or promote managed Microsoft 365 client secrets for this delegation credential. Use this when the credential owner wants to rotate the active secret outside Cal.com. Only supported for Microsoft/office365 delegation credentials; attempting to set this on a Google delegation credential returns a 400 error. CreateDelegationCredentialOutput: type: object properties: status: enum: - success - error type: string example: success data: oneOf: - title: Google Service Account $ref: '#/components/schemas/GoogleDelegationCredentialOutput' - title: Microsoft Service Account $ref: '#/components/schemas/MicrosoftDelegationCredentialOutput' required: - status - data MicrosoftDelegationCredentialWithClientIdOutput: type: object properties: id: type: string description: The unique identifier of the delegation credential example: clsx1234567890 enabled: type: boolean description: Whether the delegation credential is currently enabled example: true domain: type: string description: The email domain the delegation credential applies to example: example.com organizationId: type: number description: The unique identifier of the organization the delegation credential belongs to example: 123 workspacePlatform: $ref: '#/components/schemas/WorkspacePlatformDto' createdAt: format: date-time type: string description: The date and time when the delegation credential was created example: '2024-04-01T00:00:00.000Z' updatedAt: format: date-time type: string description: The date and time when the delegation credential was last updated example: '2024-04-01T00:00:00.000Z' optOutAutoSecretRotation: type: boolean description: Whether Cal.com-managed Microsoft 365 client secret rotation is disabled for this delegation credential. secretRotationBlocked: type: boolean description: Whether managed secret rotation is blocked after repeated failures and requires the reset-rotation endpoint before it will resume. secret: description: State of the current active managed secret. `expiresAt` is null if not yet known. allOf: - $ref: '#/components/schemas/SecretDto' pendingSecret: description: State of a replacement secret minted and pending validation/promotion. `createdAt` and `expiresAt` are null when there is no pending secret in flight. allOf: - $ref: '#/components/schemas/PendingSecretDto' secretRotationErrorCode: enum: - missing_permission - tenant_lifetime_policy - transient - unknown - pending_secret_mint_failed - pending_secret_promotion_failed type: - string - 'null' description: Why the most recent secret rotation attempt failed, or which stage terminally failed, or null if rotation has not failed. This enum is open — new values may be added over time, so treat any value you don't recognize as `unknown`. See the Cal.com docs' 'Microsoft 365 (Azure) Secret Auto-Rotation' section for per-code remediation guidance. example: missing_permission serviceAccountClientId: type: - string - 'null' description: The client id of the service account associated with the delegation credential. The service account's private key is never returned. example: '1234567890' required: - id - enabled - domain - organizationId - workspacePlatform - createdAt - updatedAt - optOutAutoSecretRotation - secretRotationBlocked - secret - pendingSecret - secretRotationErrorCode - serviceAccountClientId GoogleDelegationCredentialOutput: type: object properties: id: type: string description: The unique identifier of the delegation credential example: clsx1234567890 enabled: type: boolean description: Whether the delegation credential is currently enabled example: true domain: type: string description: The email domain the delegation credential applies to example: example.com organizationId: type: number description: The unique identifier of the organization the delegation credential belongs to example: 123 workspacePlatform: $ref: '#/components/schemas/WorkspacePlatformDto' createdAt: format: date-time type: string description: The date and time when the delegation credential was created example: '2024-04-01T00:00:00.000Z' updatedAt: format: date-time type: string description: The date and time when the delegation credential was last updated example: '2024-04-01T00:00:00.000Z' required: - id - enabled - domain - organizationId - workspacePlatform - createdAt - updatedAt MicrosoftDelegationCredentialOutput: type: object properties: id: type: string description: The unique identifier of the delegation credential example: clsx1234567890 enabled: type: boolean description: Whether the delegation credential is currently enabled example: true domain: type: string description: The email domain the delegation credential applies to example: example.com organizationId: type: number description: The unique identifier of the organization the delegation credential belongs to example: 123 workspacePlatform: $ref: '#/components/schemas/WorkspacePlatformDto' createdAt: format: date-time type: string description: The date and time when the delegation credential was created example: '2024-04-01T00:00:00.000Z' updatedAt: format: date-time type: string description: The date and time when the delegation credential was last updated example: '2024-04-01T00:00:00.000Z' optOutAutoSecretRotation: type: boolean description: Whether Cal.com-managed Microsoft 365 client secret rotation is disabled for this delegation credential. secretRotationBlocked: type: boolean description: Whether managed secret rotation is blocked after repeated failures and requires the reset-rotation endpoint before it will resume. secret: description: State of the current active managed secret. `expiresAt` is null if not yet known. allOf: - $ref: '#/components/schemas/SecretDto' pendingSecret: description: State of a replacement secret minted and pending validation/promotion. `createdAt` and `expiresAt` are null when there is no pending secret in flight. allOf: - $ref: '#/components/schemas/PendingSecretDto' secretRotationErrorCode: enum: - missing_permission - tenant_lifetime_policy - transient - unknown - pending_secret_mint_failed - pending_secret_promotion_failed type: - string - 'null' description: Why the most recent secret rotation attempt failed, or which stage terminally failed, or null if rotation has not failed. This enum is open — new values may be added over time, so treat any value you don't recognize as `unknown`. See the Cal.com docs' 'Microsoft 365 (Azure) Secret Auto-Rotation' section for per-code remediation guidance. example: missing_permission required: - id - enabled - domain - organizationId - workspacePlatform - createdAt - updatedAt - optOutAutoSecretRotation - secretRotationBlocked - secret - pendingSecret - secretRotationErrorCode SecretDto: type: object properties: expiresAt: format: date-time type: - string - 'null' description: The date and time the current active managed secret expires. Null if not yet known. example: '2024-10-01T00:00:00.000Z' required: - expiresAt MicrosoftServiceAccountKeyInput: type: object properties: private_key: type: string tenant_id: type: string client_id: type: string required: - private_key - tenant_id - client_id GoogleServiceAccountKeyInput: type: object properties: private_key: type: string client_email: type: string client_id: type: string required: - private_key - client_email - client_id UpdateDelegationCredentialOutput: type: object properties: status: enum: - success - error type: string example: success data: oneOf: - title: Google Service Account $ref: '#/components/schemas/GoogleDelegationCredentialOutput' - title: Microsoft Service Account $ref: '#/components/schemas/MicrosoftDelegationCredentialOutput' required: - status - data CreateMicrosoftDelegationCredentialInput: type: object properties: domain: type: string workspacePlatformSlug: type: string enum: - office365 serviceAccountKey: $ref: '#/components/schemas/MicrosoftServiceAccountKeyInput' optOutAutoSecretRotation: type: boolean description: When true, Cal.com will not mint or promote managed Microsoft 365 client secrets for this delegation credential. Use this when the credential owner wants to rotate the active secret outside Cal.com. required: - domain - workspacePlatformSlug - serviceAccountKey GetDelegationCredentialOutput: type: object properties: status: enum: - success - error type: string example: success description: The status of the request, either `success` or `error` data: description: The delegation credential matching the requested id oneOf: - title: Google Service Account $ref: '#/components/schemas/GoogleDelegationCredentialWithClientIdOutput' - title: Microsoft Service Account $ref: '#/components/schemas/MicrosoftDelegationCredentialWithClientIdOutput' - title: Delegation Credential $ref: '#/components/schemas/DelegationCredentialWithClientIdOutput' required: - status - data GoogleDelegationCredentialWithClientIdOutput: type: object properties: id: type: string description: The unique identifier of the delegation credential example: clsx1234567890 enabled: type: boolean description: Whether the delegation credential is currently enabled example: true domain: type: string description: The email domain the delegation credential applies to example: example.com organizationId: type: number description: The unique identifier of the organization the delegation credential belongs to example: 123 workspacePlatform: $ref: '#/components/schemas/WorkspacePlatformDto' createdAt: format: date-time type: string description: The date and time when the delegation credential was created example: '2024-04-01T00:00:00.000Z' updatedAt: format: date-time type: string description: The date and time when the delegation credential was last updated example: '2024-04-01T00:00:00.000Z' serviceAccountClientId: type: - string - 'null' description: The client id of the service account associated with the delegation credential. The service account's private key is never returned. example: '1234567890' required: - id - enabled - domain - organizationId - workspacePlatform - createdAt - updatedAt - serviceAccountClientId PendingSecretDto: type: object properties: createdAt: format: date-time type: - string - 'null' description: The date and time a replacement secret was minted and is pending validation/promotion. Null when there is no pending secret in flight. example: '2024-10-01T00:00:00.000Z' expiresAt: format: date-time type: - string - 'null' description: The date and time the pending (not-yet-active) managed secret expires. Null when there is no pending secret in flight. example: '2024-10-01T00:00:00.000Z' required: - createdAt - expiresAt x-provenance: method: harvested publisher: Cal.com source: https://cal.com/docs/api-reference/v2/openapi.json note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)