openapi: 3.1.0
info:
  title: Management API
  version: v1.23.0
  description: |
    # Introduction

    The MATTR Management API enables administrators to perform actions that span across multiple tenants. It provides capabilities for creating, updating, and managing tenants, as well as configuring access controls, defining who can access each tenant, with what roles, and which permissions. This API is essential for orchestrating large-scale deployments and maintaining centralized oversight of your digital trust infrastructure.

    # Pagination
    Most list operations in the API use pagination that can be controlled by a cursor method using the `cursor` and `limit` query parameters.

    **Example on [Retrieve List of Credentials](#operation/retrieveListCreds)**
    ```
    GET https://manage.mattr.global/v1/tenants
    ?limit=100
    &cursor=Y3JlYXRlZEF0PTIwMjAtMTAtMDhUMjMlM0ExMyUzQTE3Ljg5NtZGUxZWEyNzQ4MWI4
    ```

    * The `nextCursor` is found at the start of each returned range of credential entries and identifies the last object in the list.
    * The `limit` determines how many entries are returned in that request, with a maximum value of 1000.

    Requesting a page after the last value in the list will return an empty `data` object.

    ``` json
    {
    "data": []
    }
    ```

    Not using a query parameter defaults the response to return the first range of credential entries with a limit of 100.

    # Authorization
    The Management API is a separate set of APIs to MATTR VII. It uses machine-to-machine authentication through its own credentials, which are different from your MATTR VII client credentials.

    As part of onboarding you will be provided with the required details to make a call to a dedicated management API authorization provider and receive a bearer token.

    This token is then used in an `authorization` header on all calls identified as requiring `bearerAuth` (this is required for the majority of management operations).

    <SecurityDefinitions />
  contact:
    email: support@mattr.global
servers:
  - url: https://manage.mattr.global
security:
  - bearerAuth: []
tags:
  - name: Environments
    description: Operations for managing environments.
  - name: Tenants
    description: Operations for managing tenants within environments.
  - name: Clients
    description: Operations for managing clients within tenants.
  - name: Users
    description: Operations for managing users and their information.
  - name: Members
    description: Operations for managing tenant members and their roles.
paths:
  /oauth/token:
    servers:
      - url: https://auth.manage.mattr.global
    post:
      summary: Create API Auth Token
      operationId: authToken
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthTokenResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenErrorResponse'
              examples:
                Invalid credentials:
                  value:
                    error: access_denied
                    error_description: Unauthorized
      description: Returns an API access token specific to the Management API. This token must then be used as an authorization header for all requests to protected endpoints (this is required for the majority of operations).
      security: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthTokenRequest'
            examples:
              Request:
                value:
                  client_id: htf792W4p4MedZbnoWAs51EfqUt4d2
                  client_secret: d3fYDX7FjPg1D1h2viARXsolPByQ9vMfg8LHylBy8F4s5KJLB4HhHGOxxqJnSj3G
                  audience: https://my-tenant.vii.mattr.global
                  grant_type: client_credentials
      tags:
        - Security
      x-codeSamples:
        - lang: curl
          source: |
            curl --request POST \
              --url https://auth.manage.mattr.global/oauth/token/ \
              --header 'Content-Type: application/json' \
              --data '{"client_id": "KWdv9qo9Vnl9rrCRB7sfGKFTp4uO09im",
                       "client_secret": "ztJe2GVpOb1_rUo9Vnl9rrCRB7sfGKFTp4uO0DOfLnA5FSz96wbrzgJMQ",
                       "audience": "https://my-tenant.vii.mattr.global",
                       "grant_type": "client_credentials"
                      }'
                        '/v1/environments':
  /v1/environments:
    get:
      operationId: getEnvironments
      summary: Retrieve environments
      description: |-
        Retrieves a list of all available environments.

        ### **Analytic events**
        * ENVIRONMENT_RETRIEVE_LIST_START
        * ENVIRONMENT_RETRIEVE_LIST_SUCCESS
        * ENVIRONMENT_RETRIEVE_LIST_FAIL
      tags:
        - Environments
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: A list of environments
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/environment'
                  nextCursor:
                    $ref: '#/components/schemas/nextCursor'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
  /v1/tenants:
    get:
      operationId: getTenants
      summary: Retrieve tenants
      description: |-
        Retrieves a list of all available tenants. If you haven't created any tenants, the response will include an empty array.

        ### **Analytic events**
        * TENANT_RETRIEVE_LIST_START
        * TENANT_RETRIEVE_LIST_SUCCESS
        * TENANT_RETRIEVE_LIST_FAIL
      tags:
        - Tenants
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: A list of tenants
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/tenant'
                  nextCursor:
                    $ref: '#/components/schemas/schemas-nextCursor'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
    post:
      operationId: createTenant
      summary: Create tenant
      description: |-
        Creates a new tenant in the requested environment.

        ### **Analytic events**
        * TENANT_CREATE_START
        * TENANT_CREATE_SUCCESS
        * TENANT_CREATE_FAIL
      tags:
        - Tenants
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - subdomain
                - environmentId
              properties:
                name:
                  type: string
                  example: My Tenant
                  description: Friendly and/or meaningful name for your new tenant.
                subdomain:
                  type: string
                  example: my-tenant
                  description: Subdomain for your tenant within requested environment. Only lower case alphanumeric characters (a-z, 0-9) and hyphens are allowed.
                environmentId:
                  type: string
                  example: 84ca6f53-5405-4413-a6ad-848b781807e7
                  description: Unique identifier of the environment where you want to create your tenant. This can be obtained by [retrieving environments](#operation/getEnvironments).
      responses:
        '201':
          description: Tenant created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenantWithCredentials'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - type: object
                    title: BadRequestError
                    required:
                      - code
                      - message
                    description: The environment/subdomain provided was not available.
                    properties:
                      code:
                        type: string
                        example: BadRequest
                      message:
                        type: string
                        example: Environment is not available
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /v1/tenants/{tenantId}:
    get:
      operationId: getTenant
      summary: Retrieve tenant
      description: |-
        Retrieves a tenant by its ID.

        ### **Analytic events**
        * TENANT_RETRIEVE_START
        * TENANT_RETRIEVE_SUCCESS
        * TENANT_RETRIEVE_FAIL
      tags:
        - Tenants
      parameters:
        - name: tenantId
          in: path
          description: Unique ID of the tenant to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Tenant retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenant'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    delete:
      summary: Delete tenant
      operationId: deleteTenant
      description: |-
        Deletes a tenant by its ID.

        ### **Analytic events**
        * TENANT_DELETE_START
        * TENANT_DELETE_SUCCESS
        * TENANT_DELETE_FAIL
      tags:
        - Tenants
      parameters:
        - name: tenantId
          in: path
          description: Unique ID of the tenant to delete.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Tenant deleted
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /v1/tenants/{tenantId}/clients:
    get:
      summary: Retrieve clients
      operationId: getTenantClients
      description: |-
        Retrieves a list of clients authorized to interact with the requested tenant.

        ### **Analytic events**
        * TENANT_CLIENT_RETRIEVE_LIST_START
        * TENANT_CLIENT_RETRIEVE_LIST_SUCCESS
        * TENANT_CLIENT_RETRIEVE_LIST_FAIL
      tags:
        - Clients
      parameters:
        - name: tenantId
          in: path
          description: Unique ID of the tenant to retrieve clients for.
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: Clients retrieved
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/clientDetails'
                  nextCursor:
                    $ref: '#/components/schemas/schemas-nextCursor'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    post:
      summary: Create a client
      operationId: createTenantClient
      description: |-
        Creates a new client for the requested tenant.

        ### **Analytic events**
        * TENANT_CLIENT_CREATE_START
        * TENANT_CLIENT_CREATE_SUCCESS
        * TENANT_CLIENT_CREATE_FAIL
      tags:
        - Clients
      parameters:
        - name: tenantId
          in: path
          description: Unique ID of the tenant to create a client for.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - roles
              properties:
                name:
                  $ref: '#/components/schemas/name'
                roles:
                  $ref: '#/components/schemas/roles'
      responses:
        '201':
          description: Client created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clientDetailsWithSecret'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /v1/tenants/{tenantId}/clients/{clientId}:
    delete:
      operationId: deleteTenantClient
      summary: Delete a client
      description: |-
        Deletes an existing client of the specified tenant.

        ### **Analytic events**
        * TENANT_CLIENT_DELETE_START
        * TENANT_CLIENT_DELETE_SUCCESS
        * TENANT_CLIENT_DELETE_FAIL
      tags:
        - Clients
      parameters:
        - name: tenantId
          in: path
          description: Identifier of the tenant to delete the client from.
          required: true
          schema:
            type: string
            format: uuid
        - name: clientId
          in: path
          description: Identifier of the client to delete.
          required: true
          schema:
            $ref: '#/components/schemas/clientId'
      responses:
        '204':
          description: Client deleted
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /v1/userinfo:
    get:
      operationId: getUserInfo
      summary: Retrieve user information
      description: |-
        Retrieves information about the currently authenticated user.

        ### **Analytic events**
        * USER_USERINFO_RETRIEVE_START
        * USER_USERINFO_RETRIEVE_SUCCESS
        * USER_USERINFO_RETRIEVE_FAIL
      tags:
        - Users
      responses:
        '200':
          description: User information retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/userInfo'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
    put:
      operationId: updateUserInfo
      summary: Update user information
      description: |-
        Updates the information of the currently authenticated user.

        ### **Analytic events**
        * USER_USERINFO_UPDATE_START
        * USER_USERINFO_UPDATE_SUCCESS
        * USER_USERINFO_UPDATE_FAIL
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  example: John Doe
                  description: User's full name.
      responses:
        '200':
          description: User information updated.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/userInfo'
                  - type: object
                    required:
                      - name
                    properties:
                      name:
                        type: string
                        example: John Doe
                        description: User's full name.
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
  /v1/tenants/{tenantId}/invitations:
    post:
      operationId: inviteTenantMember
      summary: Invite a tenant member
      description: |-
        Invites a user to join the tenant and assigns roles to them within the tenant's context. 
        If the user has not registered to the Self Service Portal yet, then they will receive an email with a link to accept the invite.
        If the user has already registered, then they will be added as a member to the tenant immediately.

        ### **Analytic events**
        * TENANT_MEMBER_INVITATION_CREATE_START
        * TENANT_MEMBER_INVITATION_CREATE_SUCCESS
        * TENANT_MEMBER_INVITATION_CREATE_FAIL
      tags:
        - Members
      parameters:
        - name: tenantId
          in: path
          description: Identifier of the tenant to add the member to.
          example: 543e0579-87b9-4705-be78-8f7f54709838
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvitationRequest'
      responses:
        '200':
          description: Member invited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationResult'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /v1/tenants/{tenantId}/members:
    get:
      operationId: getTenantMembers
      summary: Retrieve tenant members
      description: |-
        Retrieves a list of all users that have access to the tenant.

        ### **Analytic events**
        * TENANT_MEMBER_RETRIEVE_LIST_START
        * TENANT_MEMBER_RETRIEVE_LIST_SUCCESS
        * TENANT_MEMBER_RETRIEVE_LIST_FAIL
      tags:
        - Members
      parameters:
        - name: tenantId
          in: path
          description: Identifier of the tenant to retrieve.
          example: 543e0579-87b9-4705-be78-8f7f54709838
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: Tenant's members retrieved
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Member'
                  nextCursor:
                    type: string
                    example: Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
  /v1/tenants/{tenantId}/members/{userId}:
    get:
      operationId: getTenantMember
      summary: Retrieve a tenant member
      description: |-
        Retrieves an existing user that has access to the tenant.

        ### **Analytic events**
        * TENANT_MEMBER_RETRIEVE_START
        * TENANT_MEMBER_RETRIEVE_SUCCESS
        * TENANT_MEMBER_RETRIEVE_FAIL
      tags:
        - Members
      parameters:
        - name: tenantId
          in: path
          description: Identifier of the tenant.
          example: 543e0579-87b9-4705-be78-8f7f54709838
          required: true
          schema:
            type: string
            format: uuid
        - name: userId
          in: path
          description: Identifier of the user.
          example: 818f7564-49cb-4003-b041-37aec302e2c9
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Tenant member retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
  /v1/tenants/{tenantId}/memberships/{userId}:
    put:
      operationId: updateTenantMembership
      summary: Update a tenant membership
      description: |-
        Updates the membership of a user in the tenant. This includes the roles assigned to this user for this tenant.

        ### **Analytic events**
        * TENANT_MEMBERSHIP_UPDATE_START
        * TENANT_MEMBERSHIP_UPDATE_SUCCESS
        * TENANT_MEMBERSHIP_UPDATE_FAIL
      tags:
        - Members
      parameters:
        - name: tenantId
          in: path
          description: Identifier of the tenant.
          example: 543e0579-87b9-4705-be78-8f7f54709838
          required: true
          schema:
            type: string
            format: uuid
        - name: userId
          in: path
          description: Identifier of the user who's membership is being updated.
          example: 818f7564-49cb-4003-b041-37aec302e2c9
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - roles
              properties:
                roles:
                  type: array
                  description: The roles assigned to the user.
                  example:
                    - dts-provider
                    - issuer
                  items:
                    type: string
      responses:
        '200':
          description: Membership updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Membership'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
    delete:
      operationId: deleteTenantMembership
      summary: Delete a tenant membership
      description: |-
        Removes the membership of a user from the specified tenant. This will remove all user permissions for this tenant.

        ### **Analytic events**
        * TENANT_MEMBERSHIP_DELETE_START
        * TENANT_MEMBERSHIP_DELETE_SUCCESS
        * TENANT_MEMBERSHIP_DELETE_FAIL
      tags:
        - Members
      parameters:
        - name: tenantId
          in: path
          description: Identifier of the tenant the user is being removed from.
          example: 543e0579-87b9-4705-be78-8f7f54709838
          required: true
          schema:
            type: string
            format: uuid
        - name: userId
          in: path
          description: Identifier of the user being removed.
          example: 818f7564-49cb-4003-b041-37aec302e2c9
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: User removed from tenant
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    OAuthTokenResponse:
      title: OAuthTokenResponse
      type: object
      properties:
        access_token:
          type: string
          example: s2dgbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6s2dcaEROemRDf5gbRVEwTTVSVFE0TmtZME9UZzVNVEpDTlVJNFJqRTBPREExTmpZMk1qazFPQSJ9
        expires_in:
          type: number
          example: 86400
        token_type:
          type: string
          example: Bearer
      required:
        - access_token
        - expires_in
        - token_type
    TokenErrorResponse:
      title: TokenErrorResponse
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
    OAuthTokenRequest:
      title: OAuthTokenRequest
      type: object
      properties:
        client_id:
          type: string
          example: htf792W4p4MedZbnoWAs51EfqUt4d2
          description: Use the `client_id` value provided for authenticating with the Management API authentication provider as part of your on-boarding.
        client_secret:
          type: string
          example: d3fYDX7FjPg1D1h2viARXsolPByQ9vMfg8LHylBy8F4s5KJLB4HhHGOxxqJnSj3G
          description: Use the `client_secret` value provided for authenticating with the Management API authentication provider as part of your on-boarding.
        audience:
          type: string
          example: https://manage.mattr.global
          description: Use the `audience` value provided as part of your on-boarding for the Management API.
        grant_type:
          type: string
          example: client_credentials
          description: Use `client_credentials`.
      required:
        - client_id
        - client_secret
        - audience
        - grant_type
    region:
      type: object
      description: Region the environment exists in.
      title: Region
      required:
        - id
        - name
        - displayName
      properties:
        id:
          type: string
          example: 70bb433a-f0ec-4297-ad76-3b09c71311f3
          description: Unique region identifier.
        name:
          type: string
          example: AU01
          description: Region name.
        displayName:
          type: string
          example: Sydney, Australia
          description: Region display name.
    environment:
      type: object
      title: Environment
      required:
        - id
        - domain
        - authorizationServerDomain
        - deploymentModel
        - region
      properties:
        id:
          type: string
          example: fa605282-0223-4ae0-831d-af368bc39a55
          description: Unique environment identifier. This is required when [creating new tenants](#operation/createTenant) in this environment.
          readOnly: true
        name:
          type: string
          example: MATTR Public Sydney, Australia
          description: Environment name.
        domain:
          type: string
          example: vii.au01.mattr.global
          description: Environment MATTR VII domain.
        authorizationServerDomain:
          type: string
          example: manage.auth.auth0.com
          description: Environment authentication server.
        deploymentModel:
          type: string
          description: Environment deployment model.
          example: public
          enum:
            - public
            - private
        region:
          $ref: '#/components/schemas/region'
    nextCursor:
      type: string
      example: Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM
      description: Starting point for next cursor to use in a paginated list.
    ValidationError:
      title: ValidationError
      description: The request was malformed or missing required parameters.
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
            required:
              - msg
            properties:
              value:
                oneOf:
                  - type: string
                  - type: number
                  - type: boolean
                  - type: object
                  - type: array
                description: The value that was provided
              msg:
                type: string
                example: Invalid value
                description: Description of why the request is invalid
              param:
                type: string
                example: id
                description: The parameter that is invalid
              location:
                type: string
                example: body
                description: The location in either body, query, path or params
    UnauthorizedError:
      title: UnauthorizedError
      description: The request does not have a valid Authorization header
      type: string
      example: Unauthorized
    tenant:
      type: object
      title: Tenant
      properties:
        id:
          type: string
          example: 86cb97a9-5e80-4ed7-af13-a170752bb1ea
          description: Unique tenant identifier, required for managing the tenant.
        name:
          type: string
          example: My Tenant
          description: Tenant name.
        subdomain:
          type: string
          example: my-tenant.vii.au01.mattr.global
          description: Tenant subdomain, used to make requests to this tenant.
        environment:
          $ref: '#/components/schemas/environment'
        membership:
          type: object
          properties:
            roles:
              type: array
              description: The roles assigned to the user in the context of this tenant.
              minItems: 1
              example:
                - dts-provider
                - issuer
              items:
                type: string
    schemas-nextCursor:
      type: string
      example: Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM
    clientId:
      type: string
      minLength: 32
      maxLength: 32
      example: suC7IhmDIawnlqBlEOuIqBWoqppcdI5
      description: Identifier for the client to authenticate with this tenant.
    clientSecret:
      type: string
      description: Secret for the client to authenticate with this tenant.
      example: QmtShBH3mkO05ra91dNO-YyPwPbfs1iokh57IgqhzVWTAZlolCdeAGYOG2kz1
    clientCredentials:
      type: object
      required:
        - clientId
        - clientSecret
      description: Authentication details for a client who is authorized to interact with this tenant.
      properties:
        clientId:
          $ref: '#/components/schemas/clientId'
        clientSecret:
          $ref: '#/components/schemas/clientSecret'
    tenantWithCredentials:
      type: object
      allOf:
        - $ref: '#/components/schemas/tenant'
        - type: object
          required:
            - client
          properties:
            client:
              $ref: '#/components/schemas/clientCredentials'
    NotFoundError:
      title: NotFoundError
      description: The specified resource was not found.
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
            required:
              - msg
              - param
              - location
            properties:
              value:
                type: string
                description: The value that was provided
              msg:
                type: string
                example: Invalid value
                description: Description of why the request is invalid
              param:
                type: string
                example: id
                description: The parameter that is invalid
              location:
                type: string
                example: body
                description: The location in either body, query, path or params
    clientDetails:
      type: object
      required:
        - clientId
        - name
        - permissions
        - roles
      properties:
        clientId:
          $ref: '#/components/schemas/clientId'
        name:
          type: string
          example: Example client
          description: Name of the client associated with this tenant.
        permissions:
          type: array
          items:
            type: string
          example:
            - dids:read
            - dids:create
          description: A list of permissions assigned to the client.
        roles:
          type: array
          items:
            type: string
            enum:
              - admin
              - issuer
              - verifier
              - dts-provider
              - dts-consumer
              - auditor
          example:
            - issuer
          description: A list of roles assigned to the client.
    name:
      type: string
      example: Example client
      description: Name of the client associated with this tenant.
    roles:
      type: array
      items:
        type: string
        enum:
          - admin
          - issuer
          - verifier
          - dts-provider
          - dts-consumer
          - auditor
      example:
        - issuer
      description: A list of roles assigned to the client.
    clientDetailsWithSecret:
      type: object
      allOf:
        - $ref: '#/components/schemas/clientDetails'
        - type: object
          required:
            - clientSecret
          properties:
            clientSecret:
              $ref: '#/components/schemas/clientSecret'
    PricingPlan:
      type: object
      title: Pricing Plan
      description: The pricing plan associated with a user.
      required:
        - type
      properties:
        type:
          type: string
          description: The type of pricing plan.
          example: Standard
          enum:
            - Standard
            - Trial
        endDate:
          type: string
          format: date-time
          description: The end date of the pricing plan. Only present when the pricing plan `type` is `Trial`.
    UserStatus:
      type: string
      description: |-
        Indicates the user's registration status:
        - Active: User has accepted their invite and registered with the MATTR Self Service Portal.
        - Pending: An invite was sent to the user, but they had not registered yet.
        - Invite Expired: The registration invite had expired before the user registered.
        - Disabled: The user has been disabled in the MATTR Self Service Portal.
      example: Active
      enum:
        - Pending
        - Active
        - Invite Expired
        - Disabled
    userInfo:
      type: object
      title: User
      required:
        - id
        - pricingPlan
        - status
      properties:
        id:
          type: string
          example: 8f6d40a9-d913-45e8-aa3e-8c99d62cd8fb
          description: User's unique identifier.
        email:
          type: string
          example: john-doe@example.com
          description: User's email address.
        name:
          type: string
          example: John Doe
          description: User's full name.
        pricingPlan:
          $ref: '#/components/schemas/PricingPlan'
        status:
          $ref: '#/components/schemas/UserStatus'
        connectionStrategy:
          type: string
          example: auth0
          description: The authentication strategy used to log in.
    InvitationRequest:
      type: object
      title: InvitationRequest
      required:
        - email
        - roles
      properties:
        email:
          type: string
          format: email
          example: john-doe@example.com
        roles:
          type: array
          description: The roles assigned to the user in the context of this tenant.
          minItems: 1
          example:
            - dts-provider
            - issuer
          items:
            type: string
    InvitationResult:
      type: object
      title: InvitationResult
      required:
        - userId
        - status
      properties:
        userId:
          type: string
          example: 8f6d40a9-d913-45e8-aa3e-8c99d62cd8fb
          description: User's unique identifier.
        status:
          $ref: '#/components/schemas/UserStatus'
        inviteExpiresAt:
          type: string
          format: date-time
          example: '2025-08-22T07:46:09.510Z'
          description: The date and time when the invite expires. Only present when `status` is `Pending`.
    Member:
      type: object
      title: Member
      required:
        - id
        - email
        - status
        - roles
        - permissions
      properties:
        id:
          type: string
          example: 8f6d40a9-d913-45e8-aa3e-8c99d62cd8fb
          description: User's unique identifier.
        email:
          type: string
          example: john-doe@example.com
          description: User's email address.
        name:
          type: string
          example: John Doe
          description: User's full name.
        status:
          $ref: '#/components/schemas/UserStatus'
        roles:
          type: array
          description: The roles assigned to the user.
          example:
            - dts-provider
            - issuer
          items:
            type: string
        permissions:
          type: array
          items:
            type: string
          example:
            - dids:read
            - dids:create
          description: A list of permissions assigned to the user.
        inviteExpiresAt:
          type: string
          format: date-time
          example: '2025-08-22T12:00:00.000Z'
          description: The date and time when the invite expires. Only present when `status` is `Pending`.
    Membership:
      type: object
      title: Membership
      required:
        - userId
        - tenantId
        - roles
      properties:
        userId:
          type: string
          example: 879a5524-d515-4aee-824a-c52fdcd4eea6
          description: User ID.
        tenantId:
          type: string
          example: 8f49b206-e0bb-474d-8a4d-62186a9de886
          description: Tenant ID.
        roles:
          type: array
          description: The roles assigned to the user.
          example:
            - dts-provider
            - issuer
          items:
            type: string
  parameters:
    limit:
      schema:
        type: number
        example: 2
        maximum: 1000
        minimum: 1
        default: 100
      in: query
      name: limit
      description: Range size of returned list.
    cursor:
      schema:
        type: string
        example: Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h
      in: query
      name: cursor
      description: Starting point for the list of entries.
  responses:
    '400':
      description: Bad Request. The request was malformed or missing required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    '401':
      description: Unauthorized. The client is not recognized by authorization server.
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
    '403':
      description: Forbidden. The client is recognized by authorization server but is not allowed to access this resource.
    '404':
      description: Not Found. The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    '500':
      description: Internal Server Error. An unexpected error occurred.
    '503':
      description: Service Unavailable. The server is temporarily unavailable to handle requests.