Skip to content

armgit / meet

Public Imported from GitHub
0

Open source video conferencing app powered by LiveKit. Built with Django and React.

15.1 KB
Raw Blame
openapi: 3.0.3
info:
  title: Meet External API
  version: 1.0.0
  description: |
    External API for room management with resource server authentication.
    [[description by Oauth 2.0]](https://www.oauth.com/oauth2-servers/the-resource-server/)
    
    #### Authentication Flow
    
    1. Authenticate with the authorization server using your credentials
    2. During authentication, request the scopes you need: `lasuite_visio` (mandatory) plus action-specific scopes
    3. Receive an access token and a refresh token that includes the requested scopes
    4. Use the access token in the `Authorization: Bearer <token>` header for all API requests
    5. When the access token expires, use the refresh token to obtain a new access token without re-authenticating
    
    #### Scopes
    
    * `lasuite_visio` - **Mandatory** Base scope required for any API access
    * `lasuite_visio:rooms:list` – List rooms accessible to the delegated user.
    * `lasuite_visio:rooms:retrieve` – Retrieve details of a specific room.
    * `lasuite_visio:rooms:create` – Create new rooms.
    * `lasuite_visio:rooms:update` – Update the access level and configuration of existing rooms.
    * `lasuite_visio:rooms:delete` – **Coming soon** Delete rooms generated by the application.
    
    #### Upcoming Features
    
    * **Add attendees to a room:** You will be able to update a room to include a list of attendees, allowing them to bypass the lobby system automatically.
    * **Delete application-generated rooms:** Rooms created via the application can be deleted when no longer needed.

  contact:
    name: API Support
    email: [email protected]

servers:
  - url: https://visio-sandbox.beta.numerique.gouv.fr/external-api/v1.0
    description: Sandbox server

tags:
  - name: Rooms
    description: Room management operations

paths:
  /rooms:
    get:
      tags:
        - Rooms
      summary: List rooms
      description: |
        Returns a list of rooms accessible to the authenticated user.
        Only rooms where the user has access will be returned.
      operationId: listRooms
      security:
        - BearerAuth: [rooms:list]
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          description: Number of items per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: List of accessible rooms
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of rooms
                  next:
                    type: string
                    nullable: true
                    description: URL to next page
                  previous:
                    type: string
                    nullable: true
                    description: URL to previous page
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Room'
              examples:
                roomList:
                  summary: Paginated room list
                  value:
                    count: 2
                    next: "https://visio-sandbox.beta.numerique.gouv.fr/external-api/v1.0/rooms?page=2"
                    previous: null
                    results:
                      - id: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
                        slug: "aae-erez-aaz"
                        access_level: "trusted"
                        url: "https://visio-sandbox.beta.numerique.gouv.fr/aae-erez-aaz"
                        telephony:
                          enabled: true
                          pin_code: "123456"
                          phone_number: "+1-555-0100"
                          default_country: "US"
                        configuration: { }
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /rooms/:
    post:
      tags:
        - Rooms
      summary: Create a room
      description: |
        Creates a new room with secure defaults for external API usage.

        **Defaults:**
        - user is set as owner
        - Room slug auto-generated for uniqueness
        - Telephony PIN auto-generated when enabled
        - Creation tracked with application client_id for auditing
      operationId: createRoom
      security:
        - BearerAuth: [rooms:create]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoomCreate'
            examples:
              emptyBody:
                summary: No parameters (use all defaults)
                value: { }
              withAccessLevel:
                summary: Specify access level
                value:
                  access_level: "trusted"
              withConfiguration:
                summary: Provide room configuration
                value:
                  configuration:
                    everyone_can_mute: true
      responses:
        '201':
          description: Room created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Room'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'

  /rooms/{id}:
    get:
      tags:
        - Rooms
      summary: Retrieve a room
      description: Get detailed information about a specific room by its ID
      operationId: retrieveRoom
      security:
        - BearerAuth: [rooms:retrieve]
      parameters:
        - name: id
          in: path
          required: true
          description: Room UUID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Room details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Room'
              examples:
                room:
                  summary: Room details
                  value:
                    id: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
                    slug: "aae-erez-aaz"
                    access_level: "trusted"
                    url: "https://visio-sandbox.beta.numerique.gouv.fr/aae-erez-aaz"
                    telephony:
                      enabled: true
                      pin_code: "123456"
                      phone_number: "+1-555-0100"
                      default_country: "US"
                    configuration: { }
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/RoomNotFoundError'

    patch:
      tags:
        - Rooms
      summary: Update a room
      description: |
        Partially updates a room. Only rooms where the user is administrator or
        owner can be updated; any other role gets a `403`.

        **Updatable fields:** `access_level` and `configuration`. Every other field
        (`id`, `name`, `slug`, `pin_code`) is read-only and silently ignored when sent.

        `configuration` is replaced as a whole, it is not merged with the stored one.
        Send the complete object you want the room to end up with.

        Full replacement (`PUT`) is not supported. Use `PATCH` instead.
      operationId: updateRoom
      security:
        - BearerAuth: [rooms:update]
      parameters:
        - name: id
          in: path
          required: true
          description: Room UUID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoomUpdate'
            examples:
              accessLevelOnly:
                summary: Change the access level
                value:
                  access_level: "restricted"
              configurationOnly:
                summary: Replace the room configuration
                value:
                  configuration:
                    everyone_can_mute: true
      responses:
        '200':
          description: Room updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Room'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/RoomNotFoundError'
        '405':
          description: |
            Method not allowed, `PUT` is not supported on this endpoint.

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT token obtained from the `/application/token` endpoint.
        Include in requests as: `Authorization: Bearer <token>`

  schemas:
    RoomCreate:
      type: object
      description: |
        Optional fields for room creation. All fields have secure defaults if omitted.
      properties:
        access_level:
          $ref: '#/components/schemas/RoomAccessLevel'
        configuration:
          $ref: '#/components/schemas/RoomConfiguration'

    RoomUpdate:
      type: object
      description: |
        Fields that can be updated on an existing room. Both are optional, omitted
        fields keep their current value.
      properties:
        access_level:
          $ref: '#/components/schemas/RoomAccessLevel'
        configuration:
          $ref: '#/components/schemas/RoomConfiguration'

    RoomConfiguration:
      type: object
      description: |
        Optional room behaviour settings. Unknown fields are rejected.
        All fields are optional and default to `null` (server-side defaults apply).
      properties:
        can_publish_sources:
          type: array
          nullable: true
          description: |
            Restricts which media tracks participants are allowed to publish.
            If `null`, all sources are permitted.
          items:
            type: string
            enum:
              - camera
              - microphone
              - screen_share
              - screen_share_audio
          example: [ "camera", "microphone" ]
        everyone_can_mute:
          type: boolean
          nullable: true
          description: |
            Whether any participant can mute others, or only the room owner/moderator.
            If `null`, the server default applies.
          example: true
      additionalProperties: false

    RoomAccessLevel:
      type: string
      enum:
        - public
        - trusted
        - restricted
      description: |
        Controls who can join the room without going through the lobby.

        - `public`: Anyone with the room link can join directly, no authentication required.
        - `trusted`: Authenticated users join directly. Unauthenticated users wait in the lobby for approval.
        - `restricted`: Only participants explicitly trusted by the owner bypass the lobby. Everyone else waits for approval regardless of authentication.

        `public` is rejected with a `400` unless the deployment explicitly enables it
        for this API. This applies both when creating a room and when updating one.
      example: "trusted"

    Room:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique room identifier
          example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
        slug:
          type: string
          readOnly: true
          description: URL-friendly room identifier (auto-generated)
          example: "aze-eere-zer"
        access_level:
          $ref: '#/components/schemas/RoomAccessLevel'
        url:
          type: string
          format: uri
          readOnly: true
          description: Full URL to access the room
          example: "https://visio-sandbox.beta.numerique.gouv.fr/aze-eere-zer"
        telephony:
          type: object
          readOnly: true
          description: Telephony dial-in information (if enabled)
          properties:
            enabled:
              type: boolean
              description: Whether telephony is available
              example: true
            pin_code:
              type: string
              description: PIN code for dial-in access
              example: "123456"
            phone_number:
              type: string
              description: Phone number to dial
              example: "+1-555-0100"
            default_country:
              type: string
              description: Default country code
              example: "US"
        configuration:
          $ref: '#/components/schemas/RoomConfiguration'

    OAuthError:
      type: object
      description: OAuth2-compliant error response
      properties:
        error:
          type: string
          description: Human-readable error description
          example: "Invalid credentials"

    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message
          example: "Invalid token."

    ValidationError:
      type: object
      properties:
        field_name:
          type: array
          items:
            type: string
          description: List of validation errors for this field
          example: ["This field is required."]

  responses:
    UnauthorizedError:
      description: The access token is expired, revoked, malformed, or invalid for other reasons. The client can obtain a new access token and try again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidToken:
              summary: Invalid token
              value:
                error: "Invalid token."

    ForbiddenError:
      description: Insufficient scope for this operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            insufficientScope:
              summary: Missing required scope
              value:
                detail: "Insufficient permissions. Required scope: 'rooms:xxxx'"

    RoomNotFoundError:
      description: Room not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            roomNotFound:
              summary: Room does not exist
              value:
                detail: "Not found."

    BadRequestError:
      description: Invalid request data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          examples:
            validationError:
              summary: Field validation failed
              value:
                scope: ["Invalid email address."]