Cal.com Deprecated: Platform / Managed Users API

openapi: 3.2.0
info:
  title: 'Cal.com API v2 Deprecated: Platform / Managed Users API'
  description: ''
  version: 1.0.0
  contact: {}
servers: []
tags:
- name: 'Deprecated: Platform / Managed Users'
paths:
  /v2/oauth-clients/{clientId}/users:
    get:
      description: These endpoints are deprecated and will be removed in the future.
      operationId: OAuthClientUsersController_getManagedUsers
      parameters:
      - name: x-cal-secret-key
        in: header
        description: OAuth client secret key
        required: true
        schema:
          type: string
      - name: clientId
        required: true
        in: path
        schema:
          type: string
      - name: limit
        required: false
        in: query
        description: The number of items to return
        schema:
          minimum: 1
          maximum: 250
          example: 10
          type: number
      - name: offset
        required: false
        in: query
        description: The number of items to skip
        schema:
          minimum: 0
          maximum: 250
          example: 0
          type: number
      - name: emails
        required: false
        in: query
        description: Filter managed users by email. If you want to filter by multiple emails, separate them with a comma.
        schema:
          minItems: 1
          example: ?emails=email1@example.com,email2@example.com
          type: array
          items:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetManagedUsersOutput'
      summary: Get all managed users
      tags:
      - 'Deprecated: Platform / Managed Users'
    post:
      description: These endpoints are deprecated and will be removed in the future.
      operationId: OAuthClientUsersController_createUser
      parameters:
      - name: x-cal-secret-key
        in: header
        description: OAuth client secret key
        required: true
        schema:
          type: string
      - name: clientId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateManagedUserInput'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateManagedUserOutput'
      summary: Create a managed user
      tags:
      - 'Deprecated: Platform / Managed Users'
  /v2/oauth-clients/{clientId}/users/{userId}:
    get:
      description: These endpoints are deprecated and will be removed in the future.
      operationId: OAuthClientUsersController_getUserById
      parameters:
      - name: x-cal-secret-key
        in: header
        description: OAuth client secret key
        required: true
        schema:
          type: string
      - name: clientId
        required: true
        in: path
        schema:
          type: string
      - name: userId
        required: true
        in: path
        schema:
          type: number
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetManagedUserOutput'
      summary: Get a managed user
      tags:
      - 'Deprecated: Platform / Managed Users'
    patch:
      description: These endpoints are deprecated and will be removed in the future.
      operationId: OAuthClientUsersController_updateUser
      parameters:
      - name: x-cal-secret-key
        in: header
        description: OAuth client secret key
        required: true
        schema:
          type: string
      - name: clientId
        required: true
        in: path
        schema:
          type: string
      - name: userId
        required: true
        in: path
        schema:
          type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateManagedUserInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetManagedUserOutput'
      summary: Update a managed user
      tags:
      - 'Deprecated: Platform / Managed Users'
    delete:
      description: These endpoints are deprecated and will be removed in the future.
      operationId: OAuthClientUsersController_deleteUser
      parameters:
      - name: x-cal-secret-key
        in: header
        description: OAuth client secret key
        required: true
        schema:
          type: string
      - name: clientId
        required: true
        in: path
        schema:
          type: string
      - name: userId
        required: true
        in: path
        schema:
          type: number
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetManagedUserOutput'
      summary: Delete a managed user
      tags:
      - 'Deprecated: Platform / Managed Users'
  /v2/oauth-clients/{clientId}/users/{userId}/force-refresh:
    post:
      description: 'These endpoints are deprecated and will be removed in the future. If you have lost managed user access or refresh token, then you can get new ones by using OAuth credentials. Access token is valid for 60 minutes and refresh token for 1 year. Make sure to store them in your database, for example, in your User database model `calAccessToken` and `calRefreshToken` fields.

        Response also contains `accessTokenExpiresAt` and `refreshTokenExpiresAt` fields, but if you decode the jwt token the payload will contain `clientId` (OAuth client ID), `ownerId` (user to whom token belongs ID), `iat` (issued at time) and `expiresAt` (when does the token expire) fields.'
      operationId: OAuthClientUsersController_forceRefresh
      parameters:
      - name: x-cal-secret-key
        in: header
        description: OAuth client secret key
        required: true
        schema:
          type: string
      - name: userId
        required: true
        in: path
        schema:
          type: number
      - name: clientId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeysResponseDto'
      summary: Force refresh tokens
      tags:
      - 'Deprecated: Platform / Managed Users'
  /v2/oauth/{clientId}/refresh:
    post:
      description: 'These endpoints are deprecated and will be removed in the future. If managed user access token is expired then get a new one using this endpoint - it will also refresh the refresh token, because we use

        "refresh token rotation" mechanism. Access token is valid for 60 minutes and refresh token for 1 year. Make sure to store them in your database, for example, in your User database model `calAccessToken` and `calRefreshToken` fields.

        Response also contains `accessTokenExpiresAt` and `refreshTokenExpiresAt` fields, but if you decode the jwt token the payload will contain `clientId` (OAuth client ID), `ownerId` (user to whom token belongs ID), `iat` (issued at time) and `expiresAt` (when does the token expire) fields.'
      operationId: OAuthFlowController_refreshTokens
      parameters:
      - name: clientId
        required: true
        in: path
        schema:
          type: string
      - name: x-cal-secret-key
        required: true
        in: header
        description: OAuth client secret key.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshTokenInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeysResponseDto'
      summary: Refresh managed user tokens
      tags:
      - 'Deprecated: Platform / Managed Users'
components:
  schemas:
    RefreshTokenInput:
      type: object
      properties:
        refreshToken:
          type: string
          description: Managed user's refresh token.
      required:
      - refreshToken
    KeysResponseDto:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
        data:
          $ref: '#/components/schemas/KeysDto'
      required:
      - status
      - data
    GetManagedUsersOutput:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
        data:
          type: array
          items:
            $ref: '#/components/schemas/ManagedUserOutput'
      required:
      - status
      - data
    CreateManagedUserOutput:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
        data:
          $ref: '#/components/schemas/CreateManagedUserData'
      required:
      - status
      - data
    GetManagedUserOutput:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
        data:
          $ref: '#/components/schemas/ManagedUserOutput'
      required:
      - status
      - data
    CreateManagedUserData:
      type: object
      properties:
        accessToken:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
        refreshToken:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
        user:
          $ref: '#/components/schemas/ManagedUserOutput'
        accessTokenExpiresAt:
          type: number
        refreshTokenExpiresAt:
          type: number
      required:
      - accessToken
      - refreshToken
      - user
      - accessTokenExpiresAt
      - refreshTokenExpiresAt
    KeysDto:
      type: object
      properties:
        accessToken:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
        refreshToken:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
        accessTokenExpiresAt:
          type: number
        refreshTokenExpiresAt:
          type: number
      required:
      - accessToken
      - refreshToken
      - accessTokenExpiresAt
      - refreshTokenExpiresAt
    CreateManagedUserInput:
      type: object
      properties:
        email:
          type: string
          example: alice@example.com
        name:
          type: string
          example: Alice Smith
          description: Managed user's name is used in emails
        timeFormat:
          enum:
          - 12
          - 24
          type: number
          example: 12
          description: Must be a number 12 or 24
        weekStart:
          enum:
          - Monday
          - Tuesday
          - Wednesday
          - Thursday
          - Friday
          - Saturday
          - Sunday
          type: string
          example: Monday
        timeZone:
          type: string
          example: America/New_York
          description: "Timezone is used to create user's default schedule from Monday to Friday from 9AM to 5PM. If it is not passed then user does not have\n      a default schedule and it must be created manually via the /schedules endpoint. Until the schedule is created, the user can't access availability atom to set his / her availability nor booked.\n      It will default to Europe/London if not passed."
        locale:
          enum:
          - ar
          - ca
          - de
          - es
          - eu
          - he
          - id
          - ja
          - lv
          - pl
          - ro
          - sr
          - th
          - vi
          - az
          - cs
          - el
          - es-419
          - fi
          - hr
          - it
          - km
          - nl
          - pt
          - ru
          - sv
          - tr
          - zh-CN
          - bg
          - da
          - en
          - et
          - fr
          - hu
          - iw
          - ko
          - 'no'
          - pt-BR
          - sk
          - sl
          - ta
          - uk
          - zh-TW
          - bn
          type: string
          example: en
        avatarUrl:
          type: string
          format: uri
          example: https://cal.com/api/avatar/2b735186-b01b-46d3-87da-019b8f61776b.png
          description: URL of the user's avatar image
        bio:
          type: string
          description: Bio
          example: I am a bio
        metadata:
          type: object
          additionalProperties: true
          description: You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and values up to 500 characters.
          example:
            key: value
      required:
      - email
      - name
    ManagedUserOutput:
      type: object
      properties:
        id:
          type: number
          example: 1
        uuid:
          type: string
          format: uuid
          example: 3f2504e0-4f89-41d3-9a0c-0305e82c3301
        email:
          type: string
          example: alice+cluo37fwd0001khkzqqynkpj3@example.com
        username:
          type:
          - string
          - 'null'
          example: alice
        name:
          type:
          - string
          - 'null'
          example: alice
        bio:
          type:
          - string
          - 'null'
          example: bio
        timeZone:
          type: string
          example: America/New_York
        weekStart:
          type: string
          example: Sunday
        createdDate:
          type: string
          example: '2024-04-01T00:00:00.000Z'
          format: date-time
        timeFormat:
          type:
          - number
          - 'null'
          example: 12
        defaultScheduleId:
          type:
          - number
          - 'null'
          example: null
        locale:
          enum:
          - ar
          - ca
          - de
          - es
          - eu
          - he
          - id
          - ja
          - lv
          - pl
          - ro
          - sr
          - th
          - vi
          - az
          - cs
          - el
          - es-419
          - fi
          - hr
          - it
          - km
          - nl
          - pt
          - ru
          - sv
          - tr
          - zh-CN
          - bg
          - da
          - en
          - et
          - fr
          - hu
          - iw
          - ko
          - 'no'
          - pt-BR
          - sk
          - sl
          - ta
          - uk
          - zh-TW
          - bn
          type: string
          example: en
        avatarUrl:
          type:
          - string
          - 'null'
          format: uri
          example: https://cal.com/api/avatar/2b735186-b01b-46d3-87da-019b8f61776b.png
          description: URL of the user's avatar image
        metadata:
          type: object
          additionalProperties: true
          example:
            key: value
      required:
      - id
      - uuid
      - email
      - username
      - name
      - bio
      - timeZone
      - weekStart
      - createdDate
      - timeFormat
      - defaultScheduleId
    UpdateManagedUserInput:
      type: object
      properties:
        email:
          type: string
        name:
          type: string
        timeFormat:
          enum:
          - 12
          - 24
          type: number
          example: 12
          description: Must be 12 or 24
        defaultScheduleId:
          type: number
        weekStart:
          enum:
          - Monday
          - Tuesday
          - Wednesday
          - Thursday
          - Friday
          - Saturday
          - Sunday
          type: string
          example: Monday
        timeZone:
          type: string
        locale:
          enum:
          - ar
          - ca
          - de
          - es
          - eu
          - he
          - id
          - ja
          - lv
          - pl
          - ro
          - sr
          - th
          - vi
          - az
          - cs
          - el
          - es-419
          - fi
          - hr
          - it
          - km
          - nl
          - pt
          - ru
          - sv
          - tr
          - zh-CN
          - bg
          - da
          - en
          - et
          - fr
          - hu
          - iw
          - ko
          - 'no'
          - pt-BR
          - sk
          - sl
          - ta
          - uk
          - zh-TW
          - bn
          type: string
          example: en
        avatarUrl:
          type: string
          format: uri
          example: https://cal.com/api/avatar/2b735186-b01b-46d3-87da-019b8f61776b.png
          description: URL of the user's avatar image
        bio:
          type: string
          description: Bio
          example: I am a bio
        metadata:
          type: object
          additionalProperties: true
          description: You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and values up to 500 characters.
          example:
            key: value
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)