Open source video conferencing app powered by LiveKit. Built with Django and React.
π(backend) add Swagger documentation for external API
lebaudantoine69a9a07d210d
diff --git a/docs/openapi.yaml b/docs/openapi.yamlnew file mode 100644index 00000000..d13f8458--- /dev/null+++ b/docs/openapi.yaml@@ -0,0 +1,475 @@+openapi: 3.0.3+info:+ title: Meet External API+ version: 1.0.0+ description: |+ External API for room management with application-delegated authentication.++ #### Authentication Flow++ 1. Exchange application credentials for a JWT token via `/external-api/v1.0/applications/token`.+ 2. Use the JWT token in the `Authorization: Bearer <token>` header for all subsequent requests.+ 3. Tokens are scoped and allow applications to act on behalf of specific users.++ #### Scopes++ * `rooms:list` β List rooms accessible to the delegated user.+ * `rooms:retrieve` β Retrieve details of a specific room.+ * `rooms:create` β Create new rooms.+ * `rooms:update` β **Coming soon** Update existing rooms, e.g., add attendees to a room.+ * `rooms:delete` β **Coming soon** Delete rooms generated by the application.++ #### Upcoming Features++ * **Create rooms for unknown users from the web app:** Support for generating rooms for users who are not yet registered in the system.+ * **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: Authentication+ description: Application authentication and token generation+ - name: Rooms+ description: Room management operations++paths:+ /applications/token:+ post:+ tags:+ - Authentication+ summary: Generate JWT token+ description: |+ Exchange application credentials for a scoped JWT token that allows the application+ to act on behalf of a specific user.++ The application must be authorized for the user's email domain.+ The returned token expires after a configured duration and must be refreshed by calling this endpoint again.+ operationId: generateToken+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/TokenRequest'+ examples:+ tokenRequest:+ summary: Request token for user delegation+ value:+ client_id: "550e8400-e29b-41d4-a716-446655440000"+ client_secret: "1234567890abcdefghijklmnopqrstuvwxyz"+ grant_type: "client_credentials"+ scope: "[email protected]"+ responses:+ '200':+ description: Token generated successfully+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/TokenResponse'+ examples:+ tokenResponse:+ summary: Successful token generation+ value:+ access_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."+ token_type: "Bearer"+ expires_in: 3600+ scope: "rooms:list rooms:retrieve rooms:create"+ '401':+ description: Authentication failed+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/OAuthError'+ examples:+ invalidCredentials:+ summary: Invalid credentials+ value:+ error: "Invalid credentials"+ inactiveApplication:+ summary: Application is inactive+ value:+ error: "Application is inactive"+ '400':+ description: Invalid request+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/OAuthError'+ examples:+ userNotFound:+ summary: User not found+ value:+ error: "User not found."+ '403':+ description: Access denied - cannot delegate user+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/OAuthError'+ examples:+ delegationDenied:+ summary: Domain not authorized+ value:+ error: "This application is not authorized for this email domain."++ /rooms:+ get:+ tags:+ - Rooms+ summary: List rooms+ description: |+ Returns a list of rooms accessible to the authenticated user.+ Only rooms where the delegated 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"+ '401':+ $ref: '#/components/responses/UnauthorizedError'+ '403':+ $ref: '#/components/responses/ForbiddenError'++ post:+ tags:+ - Rooms+ summary: Create a room+ description: |+ Creates a new room with secure defaults for external API usage.++ **Restrictions:**+ - Rooms are always created with `trusted` access (no public rooms via API)+ - Room access_level can be updated from the webapp interface.++ **Defaults:**+ - Delegated 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 (default)+ value: {}+ 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"+ '401':+ $ref: '#/components/responses/UnauthorizedError'+ '403':+ $ref: '#/components/responses/ForbiddenError'+ '404':+ $ref: '#/components/responses/RoomNotFoundError'++components:+ securitySchemes:+ BearerAuth:+ type: http+ scheme: bearer+ bearerFormat: JWT+ description: |+ JWT token obtained from the `/applications/token` endpoint.+ Include in requests as: `Authorization: Bearer <token>`++ schemas:+ TokenRequest:+ type: object+ required:+ - client_id+ - client_secret+ - grant_type+ - scope+ properties:+ client_id:+ type: string+ description: Application client identifier+ example: "550e8400-e29b-41d4-a716-446655440000"+ client_secret:+ type: string+ format: password+ writeOnly: true+ description: Application secret key+ example: "1234567890abcdefghijklmnopqrstuvwxyz"+ grant_type:+ type: string+ enum:+ - client_credentials+ description: OAuth2 grant type (must be 'client_credentials')+ example: "client_credentials"+ scope:+ type: string+ format: email+ description: |+ Email address of the user to delegate.+ The application will act on behalf of this user.+ Note: This parameter is named 'scope' to align with OAuth2 conventions,+ but accepts an email address to identify the user. This design allows+ for future extensibility.+ example: "[email protected]"++ TokenResponse:+ type: object+ properties:+ access_token:+ type: string+ description: JWT access token+ example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtZWV0LWFwaSIsImF1ZCI6Im1lZXQtY2xpZW50cyIsImlhdCI6MTcwOTQ5MTIwMCwiZXhwIjoxNzA5NDk0ODAwLCJjbGllbnRfaWQiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJzY29wZSI6InJvb21zOmxpc3Qgcm9vbXM6cmV0cmlldmUgcm9vbXM6Y3JlYXRlIiwidXNlcl9pZCI6IjdiOGQ5YzQwLTNhMmItNGVkZi04NzFjLTJmM2Q0ZTVmNmE3YiIsImRlbGVnYXRlZCI6dHJ1ZX0.signature"+ token_type:+ type: string+ description: Token type (always 'Bearer')+ example: "Bearer"+ expires_in:+ type: integer+ description: Token lifetime in seconds+ example: 3600+ scope:+ type: string+ description: Space-separated list of granted permission scopes+ example: "rooms:list rooms:retrieve rooms:create"++ RoomCreate:+ type: object+ description: Empty object - all room properties are auto-generated+ properties: {}++ 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:+ type: string+ readOnly: true+ description: Room access level (always 'trusted' for API-created rooms)+ example: "trusted"+ 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"++ 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: Authentication required or token invalid/expired+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/Error'+ examples:+ invalidToken:+ summary: Invalid or expired token+ value:+ error: "Invalid token."+ tokenExpired:+ summary: Token has expired+ value:+ error: "Token expired."++ ForbiddenError:+ description: Insufficient permissions 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."]