openapi: 3.2.0
info:
  title: Radiant Earth Memberships API
  version: 1.0.0
  description: 'Operations tagged Memberships across 2 of this provider''s published API definitions: radiant-earth-source-cooperative-openapi.json, radiant-earth-source-cooperative-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://source.coop/api/v1
  description: Source Cooperative
security:
- ApiKeyAuth: []
tags:
- name: Memberships
paths:
  /accounts/{account_id}/members:
    post:
      tags:
      - Memberships
      summary: Invite a new member to an account
      description: 'Invites a new member to the specified account. For user accounts, you must be authenticated as the user account you are inviting the member to. For organization accounts, you must be authenticated as either an `owners` or `maintainers` member for the organization account you are inviting the member to.

        Only users with the `admin` flag may invite members to service accounts.'
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
        description: The ID of the account to invite the member to
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipInvitation'
      responses:
        '200':
          description: Successfully invited member
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Membership'
        '400':
          description: Bad request - Invalid request body or member already invited/exists
        '401':
          description: Unauthorized - No valid session found or insufficient permissions
        '404':
          description: Not Found - Account not found
        '500':
          description: Internal server error
      operationId: postAccountsByAccountIdMembers
      x-operation-id-source: derived
    get:
      tags:
      - Memberships
      summary: List the memberships for an account
      description: 'Retrieves all memberships associated with the specified account.

        For user accounts, you must be authenticated as the user account you are listing memberships for.

        For organization accounts, you must be authenticated as either an `owners` or `maintainers` member of the organization account you are listing memberships for.


        Only users with the `admin` flag may list memberships for service accounts.'
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
        description: The ID of the account to list memberships for
      responses:
        '200':
          description: Successfully retrieved memberships
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Membership'
        '401':
          description: Unauthorized - No valid session found or insufficient permissions
        '404':
          description: Not Found - Account not found
        '500':
          description: Internal server error
      operationId: getAccountsByAccountIdMembers
      x-operation-id-source: derived
    servers:
    - url: https://source.coop/api/v1
      description: Source Cooperative
  /memberships/{membership_id}/accept:
    post:
      tags:
      - Memberships
      summary: Accept a membership invitation
      description: Accepts a membership invitation for the specified membership. The user must be authorized to accept the membership.
      parameters:
      - in: path
        name: membership_id
        required: true
        schema:
          type: string
        description: The ID of the membership to accept
      responses:
        '200':
          description: Successfully accepted membership
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Membership'
        '400':
          description: Bad Request - Membership is not in a pending state
        '401':
          description: Unauthorized - No valid session found or insufficient permissions
        '404':
          description: Not Found - Membership not found
        '500':
          description: Internal server error
      operationId: postMembershipsByMembershipIdAccept
      x-operation-id-source: derived
    servers:
    - url: https://source.coop/api/v1
      description: Source Cooperative
  /memberships/{membership_id}/reject:
    post:
      tags:
      - Memberships
      summary: Rejects a membership invitation
      description: Rejects a membership invitation for the specified membership. The user must be authorized to reject the membership.
      parameters:
      - in: path
        name: membership_id
        required: true
        schema:
          type: string
        description: The ID of the membership to reject
      responses:
        '200':
          description: Successfully rejected membership
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Membership'
        '400':
          description: Bad Request - Membership is not in a pending state
        '401':
          description: Unauthorized - No valid session found or insufficient permissions
        '404':
          description: Not Found - Membership not found
        '500':
          description: Internal server error
      operationId: postMembershipsByMembershipIdReject
      x-operation-id-source: derived
    servers:
    - url: https://source.coop/api/v1
      description: Source Cooperative
  /memberships/{membership_id}/revoke:
    post:
      tags:
      - Memberships
      summary: Revokes a membership
      description: Revokes the specified membership. The user must be authorized to revoke the membership.
      parameters:
      - in: path
        name: membership_id
        required: true
        schema:
          type: string
        description: The ID of the membership to revoke
      responses:
        '200':
          description: Successfully revoked membership
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Membership'
        '400':
          description: Bad Request - Membership is already revoked
        '401':
          description: Unauthorized - No valid session found or insufficient permissions
        '404':
          description: Not Found - Membership not found
        '500':
          description: Internal server error
      operationId: postMembershipsByMembershipIdRevoke
      x-operation-id-source: derived
    servers:
    - url: https://source.coop/api/v1
      description: Source Cooperative
  /memberships/{membership_id}/update-role:
    post:
      tags:
      - Memberships
      summary: Updates a membership role
      description: Updates the specified membership. The user must be authorized to update the membership.
      parameters:
      - in: path
        name: membership_id
        required: true
        schema:
          type: string
        description: The ID of the membership to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipRole'
      responses:
        '200':
          description: Successfully updated membership
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Membership'
        '401':
          description: Unauthorized - No valid session found or insufficient permissions
        '404':
          description: Not Found - Membership not found
        '500':
          description: Internal server error
      operationId: postMembershipsByMembershipIdUpdateRole
      x-operation-id-source: derived
    servers:
    - url: https://source.coop/api/v1
      description: Source Cooperative
  /repositories/{account_id}/{repository_id}/members:
    post:
      tags:
      - Memberships
      summary: Invite a new member to a repository
      description: 'Invites a new member to the specified repository. For user accounts, you must be authenticated as the user account you are inviting the member to. For organization accounts, you must be authenticated as either an `owners` or `maintainers` member of the organization or repository you are inviting the member to.

        Users with the `admin` flag may invite users to any repository.'
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
        description: The ID of the account that owns the repository
      - in: path
        name: repository_id
        required: true
        schema:
          type: string
        description: The ID of the repository to invite the member to
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipInvitation'
      responses:
        '200':
          description: Successfully invited member
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Membership'
        '400':
          description: Bad request - Invalid request body or member already invited/exists
        '401':
          description: Unauthorized - No valid session found or insufficient permissions
        '404':
          description: Not Found - Repository not found
        '500':
          description: Internal server error
      operationId: postRepositoriesByAccountIdByRepositoryIdMembers
      x-operation-id-source: derived
    get:
      tags:
      - Memberships
      summary: List the memberships for a repository
      description: 'Retrieves all memberships associated with the specified repository.

        For user accounts, you must be authenticated as the user account you are listing memberships for.

        For organization accounts, you must be authenticated as either an `owners` or `maintainers` member for the organization or repository you are listing memberships for.


        Users with the `admin` flag may list memberships for any repository.'
      parameters:
      - in: path
        name: account_id
        required: true
        schema:
          type: string
        description: The ID of the account that owns the repository
      - in: path
        name: repository_id
        required: true
        schema:
          type: string
        description: The ID of the repository to list memberships for
      responses:
        '200':
          description: Successfully retrieved memberships
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Membership'
        '401':
          description: Unauthorized - No valid session found or insufficient permissions
        '404':
          description: Not Found - Repository not found
        '500':
          description: Internal server error
      operationId: getRepositoriesByAccountIdByRepositoryIdMembers
      x-operation-id-source: derived
    servers:
    - url: https://source.coop/api/v1
      description: Source Cooperative
components:
  schemas:
    Membership:
      type: object
      properties:
        membership_id:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        account_id:
          type: string
          minLength: 3
          maxLength: 40
          pattern: ^[a-z0-9](?:(?!--)[a-z0-9-])*[a-z0-9]$
          example: account-id
        membership_account_id:
          type: string
          minLength: 3
          maxLength: 40
          pattern: ^[a-z0-9](?:(?!--)[a-z0-9-])*[a-z0-9]$
          example: organization-id
        repository_id:
          type: string
          minLength: 3
          maxLength: 40
          pattern: ^[a-z0-9](?:(?!--)[a-z0-9-])*[a-z0-9]$
          example: repository-id
        role:
          $ref: '#/components/schemas/MembershipRole'
        state:
          $ref: '#/components/schemas/MembershipState'
        state_changed:
          type: string
          format: date-time
      required:
      - membership_id
      - account_id
      - membership_account_id
      - role
      - state
      - state_changed
    MembershipInvitation:
      type: object
      properties:
        account_id:
          type: string
          minLength: 3
          maxLength: 40
          pattern: ^[a-z0-9](?:(?!--)[a-z0-9-])*[a-z0-9]$
          example: account-id
        role:
          $ref: '#/components/schemas/MembershipRole'
      required:
      - account_id
      - role
    MembershipState:
      type: string
      enum:
      - invited
      - revoked
      - member
    MembershipRole:
      type: string
      enum:
      - owners
      - maintainers
      - read_data
      - write_data
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Follows the format `<access-key-id> <secret-access-key>`
x-refined-from:
- radiant-earth-source-cooperative-openapi.json
- radiant-earth-source-cooperative-openapi.yml