# List Members

`GET /v1/members`

Everyone with access to the organization, or to one workspace with
``project_id``: their role there and each path that gives it.

Needs ``members:read`` (and ``projects:read``, which reading any space
takes). ``can_manage_members`` says whether this caller may change people
there.

- Base URL: `https://junction-api.qualiastudios.dev`
- Authentication: an API key in the `X-API-Key` header, or `Authorization: Bearer …`

## Parameters

- `project_id` (query, string | null (uuid)): A workspace of the organization; omit it for the organization itself. A workspace key names its own workspace.

## Responses

- `200` Everyone with access and their roles: `application/json` `MemberList`
- `401` Invalid or missing API key: `application/json` `ErrorResponse`
- `403` The key lacks members:read, or its creator's role does not allow it: `application/json` `ErrorResponse`
- `404` Not found or not readable: `application/json` `ErrorResponse`
- `422` Validation Error: `application/json` `HTTPValidationError`

## Schemas

```yaml
MemberList:
  properties:
    space:
      $ref: "#/components/schemas/SpaceRef"
    people:
      items:
        $ref: "#/components/schemas/Member"
      type: array
    can_manage_members:
      type: boolean
      description: "The caller may change people here: for a key, its creator's role holds spaces:members and the key holds members:write"
      default: false
    can_create_children:
      type: boolean
      description: The caller may create, rename and delete workspaces
      default: false
    my_role:
      description: "The caller's role here: the most they may grant"
      nullable: true
      type: string
      enum:
        - viewer
        - contributor
        - admin
        - owner
  type: object
  required:
    - space
    - people
  title: MemberList
  description: Everyone with access to the organization or one workspace.
SpaceRef:
  properties:
    space_id:
      type: string
      format: uuid
    kind:
      type: string
      enum:
        - organization
        - workspace
    name:
      type: string
    slug:
      type:
        - string
        - "null"
    icon:
      description: A workspace's icon; null for none
      type:
        - string
        - "null"
  type: object
  required:
    - space_id
    - kind
    - name
  title: SpaceRef
  description: Enough of a space to name it.
Member:
  properties:
    user_id:
      type: string
      format: uuid
    email:
      type:
        - string
        - "null"
    display_name:
      type:
        - string
        - "null"
    role:
      type: string
      enum:
        - viewer
        - contributor
        - admin
        - owner
      description: Their effective role here
    paths:
      items:
        $ref: "#/components/schemas/AccessPath"
      type: array
  type: object
  required:
    - user_id
    - role
  title: Member
  description: A person with access to the space, their role and where it comes from.
AccessPath:
  properties:
    role:
      type: string
      enum:
        - viewer
        - contributor
        - admin
        - owner
    source:
      type: string
      description: direct, inherited (from the organization), membership or inherited_membership
    grant_id:
      type: string
      format: uuid
    granted_on:
      $ref: "#/components/schemas/SpaceRef"
      description: "The space the grant sits on: this one or the organization"
    via:
      description: The space whose membership carried the grant, if any
      nullable: true
      allOf:
        - $ref: "#/components/schemas/SpaceRef"
  type: object
  required:
    - role
    - source
    - grant_id
    - granted_on
  title: AccessPath
  description: One reason a person holds a role on a space.
ErrorResponse:
  properties:
    detail:
      type: string
      description: Error message describing what went wrong
  type: object
  required:
    - detail
  title: ErrorResponse
  description: Standard error response.
HTTPValidationError:
  properties:
    detail:
      items:
        $ref: "#/components/schemas/ValidationError"
      type: array
  type: object
  title: HTTPValidationError
ValidationError:
  properties:
    loc:
      items:
        type:
          - string
          - integer
      type: array
      title: Location
    msg:
      type: string
      title: Message
    type:
      type: string
      title: Error Type
    input: {}
    ctx:
      type: object
      title: Context
  type: object
  required:
    - loc
    - msg
    - type
  title: ValidationError
```