openapi: 3.0.3
info:
  title: Synapse Admin Federation Users API
  description: Administrative REST API for the Synapse Matrix homeserver. Provides server administrators with endpoints to manage users, rooms, media, federation, registration tokens, background updates, event reports, and server statistics. Authentication requires an access token belonging to a server admin account, passed as a Bearer token. Admin API endpoints should be protected behind a reverse proxy.
  version: '1.0'
  contact:
    name: Element (Synapse maintainers)
    url: https://github.com/element-hq/synapse
  license:
    name: AGPL-3.0
    url: https://github.com/element-hq/synapse/blob/develop/LICENSE
servers:
- url: https://matrix.example.com/_synapse/admin
  description: Synapse Admin API base URL
security:
- BearerAuth: []
tags:
- name: Users
  description: User account management
paths:
  /v2/users:
    get:
      summary: List All Users
      description: List all local users on the homeserver with optional filtering
      operationId: listUsers
      tags:
      - Users
      parameters:
      - name: user_id
        in: query
        schema:
          type: string
        description: Filter by user ID (prefix match)
      - name: name
        in: query
        schema:
          type: string
        description: Filter by display name or user ID
      - name: guests
        in: query
        schema:
          type: boolean
        description: Include guest accounts
      - name: deactivated
        in: query
        schema:
          type: boolean
        description: Include deactivated accounts
      - name: limit
        in: query
        schema:
          type: integer
          default: 100
        description: Maximum number of results to return
      - name: from
        in: query
        schema:
          type: integer
          default: 0
        description: Offset for pagination
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/users/{userId}:
    get:
      summary: Get User Details
      description: Get detailed information about a specific user
      operationId: getUser
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
        description: The fully qualified Matrix user ID (e.g. @user:example.com)
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      summary: Create or Modify User
      description: Create a new user account or modify an existing user
      operationId: upsertUser
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
        description: The fully qualified Matrix user ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpsert'
      responses:
        '200':
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/deactivate/{userId}:
    post:
      summary: Deactivate User Account
      description: Deactivate a user account, optionally erasing their data
      operationId: deactivateUser
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
        description: The fully qualified Matrix user ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                erase:
                  type: boolean
                  description: Whether to erase all user data
      responses:
        '200':
          description: User deactivated
          content:
            application/json:
              schema:
                type: object
                properties:
                  id_server_unbind_result:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/reset_password/{userId}:
    post:
      summary: Reset User Password
      description: Reset the password for a local user
      operationId: resetUserPassword
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - new_password
              properties:
                new_password:
                  type: string
                  description: New password for the user
                logout_devices:
                  type: boolean
                  description: Whether to log out all devices
      responses:
        '200':
          description: Password reset successfully
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/users/{userId}/rooms:
    get:
      summary: List User Rooms
      description: List all rooms that a user is a member of
      operationId: listUserRooms
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of rooms the user is in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomMembershipList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - missing or invalid access token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden - requires server admin access
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    UserList:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserSummary'
        next_token:
          type: integer
        total:
          type: integer
    UserUpsert:
      type: object
      properties:
        password:
          type: string
        displayname:
          type: string
        avatar_url:
          type: string
        admin:
          type: boolean
        deactivated:
          type: boolean
        user_type:
          type: string
    RoomMembershipList:
      type: object
      properties:
        joined_rooms:
          type: array
          items:
            type: string
        total:
          type: integer
    UserDetail:
      allOf:
      - $ref: '#/components/schemas/UserSummary'
      - type: object
        properties:
          threepids:
            type: array
            items:
              type: object
              properties:
                medium:
                  type: string
                address:
                  type: string
          external_ids:
            type: array
            items:
              type: object
          user_type:
            type: string
    UserSummary:
      type: object
      properties:
        name:
          type: string
          description: Matrix user ID
        displayname:
          type: string
        avatar_url:
          type: string
        is_guest:
          type: boolean
        deactivated:
          type: boolean
        erased:
          type: boolean
        shadow_banned:
          type: boolean
        admin:
          type: boolean
        creation_ts:
          type: integer
          format: int64
    Error:
      type: object
      properties:
        errcode:
          type: string
          description: Matrix error code (e.g. M_FORBIDDEN, M_NOT_FOUND)
        error:
          type: string
          description: Human-readable error description
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Admin access token obtained from the Synapse homeserver