Cal.com Deprecated: Platform / Managed Users API

openapi: 3.2.0
info:
  title: 'Cal.diy 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:
      operationId: OAuthClientUsersController_getManagedUsers
      summary: Get all managed users
      description: These endpoints are deprecated and will be removed in the future.
      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:
          example: 10
          type: number
      - name: offset
        required: false
        in: query
        description: The number of items to skip
        schema:
          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:
          example: ?emails=email1@example.com,email2@example.com
          type: array
          items:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetManagedUsersOutput'
      tags:
      - 'Deprecated: Platform / Managed Users'
    post:
      operationId: OAuthClientUsersController_createUser
      summary: Create a managed user
      description: These endpoints are deprecated and will be removed in the future.
      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'
      tags:
      - 'Deprecated: Platform / Managed Users'
  /v2/oauth-clients/{clientId}/users/{userId}:
    get:
      operationId: OAuthClientUsersController_getUserById
      summary: Get a managed user
      description: These endpoints are deprecated and will be removed in the future.
      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'
      tags:
      - 'Deprecated: Platform / Managed Users'
    patch:
      operationId: OAuthClientUsersController_updateUser
      summary: Update a managed user
      description: These endpoints are deprecated and will be removed in the future.
      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'
      tags:
      - 'Deprecated: Platform / Managed Users'
    delete:
      operationId: OAuthClientUsersController_deleteUser
      summary: Delete a managed user
      description: These endpoints are deprecated and will be removed in the future.
      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'
      tags:
      - 'Deprecated: Platform / Managed Users'
  /v2/oauth-clients/{clientId}/users/{userId}/force-refresh:
    post:
      operationId: OAuthClientUsersController_forceRefresh
      summary: Force refresh tokens
      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.'
      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'
      tags:
      - 'Deprecated: Platform / Managed Users'
  /v2/oauth/{clientId}/refresh:
    post:
      operationId: OAuthFlowController_refreshTokens
      summary: Refresh managed user tokens
      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.'
      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'
      tags:
      - 'Deprecated: Platform / Managed Users'
components:
  schemas:
    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:
          type: number
          enum:
          - 12
          - 24
          example: 12
          description: Must be a number 12 or 24
        weekStart:
          type: string
          example: Monday
          enum:
          - Monday
          - Tuesday
          - Wednesday
          - Thursday
          - Friday
          - Saturday
          - Sunday
        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
          - ta
          - uk
          - zh-TW
          - bn
          type: string
          example: en
        avatarUrl:
          type: string
          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
          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
    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
    CreateManagedUserOutput:
      type: object
      properties:
        status:
          type: string
          example: success
          enum:
          - success
          - error
        data:
          $ref: '#/components/schemas/CreateManagedUserData'
        error:
          type: object
      required:
      - status
      - data
    RefreshTokenInput:
      type: object
      properties:
        refreshToken:
          type: string
          description: Managed user's refresh token.
      required:
      - refreshToken
    GetManagedUsersOutput:
      type: object
      properties:
        status:
          type: string
          example: success
          enum:
          - success
          - error
        data:
          type: array
          items:
            $ref: '#/components/schemas/ManagedUserOutput'
      required:
      - status
      - data
    KeysResponseDto:
      type: object
      properties:
        status:
          type: string
          example: success
          enum:
          - success
          - error
        data:
          $ref: '#/components/schemas/KeysDto'
      required:
      - status
      - data
    UpdateManagedUserInput:
      type: object
      properties:
        email:
          type: string
        name:
          type: string
        timeFormat:
          type: number
          enum:
          - 12
          - 24
          example: 12
          description: Must be 12 or 24
        defaultScheduleId:
          type: number
        weekStart:
          type: string
          enum:
          - Monday
          - Tuesday
          - Wednesday
          - Thursday
          - Friday
          - Saturday
          - Sunday
          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
          - ta
          - uk
          - zh-TW
          - bn
          type: string
          example: en
        avatarUrl:
          type: string
          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
          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
    GetManagedUserOutput:
      type: object
      properties:
        status:
          type: string
          example: success
          enum:
          - success
          - error
        data:
          $ref: '#/components/schemas/ManagedUserOutput'
      required:
      - status
      - data
    ManagedUserOutput:
      type: object
      properties:
        id:
          type: number
          example: 1
        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'
        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
          - ta
          - uk
          - zh-TW
          - bn
          type: string
          example: en
        avatarUrl:
          type:
          - string
          - 'null'
          example: https://cal.com/api/avatar/2b735186-b01b-46d3-87da-019b8f61776b.png
          description: URL of the user's avatar image
        metadata:
          type: object
          example:
            key: value
      required:
      - id
      - email
      - username
      - name
      - bio
      - timeZone
      - weekStart
      - createdDate
      - timeFormat
      - defaultScheduleId