Macrometa Users API

openapi: 3.0.0
info:
  title: Macrometa API Reference Activity Metrics Users API
  version: 0.17.17
  description: API reference for the Macrometa Global Data Network.
  license:
    name: Macrometa License, Version 2.0
servers:
- url: https://api-play.paas.macrometa.io
  description: GDN API
host: api-play.paas.macrometa.io
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Users
paths:
  /_api/version:
    get:
      description: Fetch the server name and version number.
      operationId: RestVersionHandler
      responses:
        '200':
          description: Successfully fetched server name and version number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_api_return_rc_200'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
      summary: Return server version
      tags:
      - Users
  /_api/user:
    post:
      description: 'Create a new user.


        **Note**: Requires *administrator* permissions.'
      operationId: CreateUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/user_create'
        required: true
      responses:
        '201':
          description: Successfully created user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    description: HTTP response code.
                    type: integer
                    example: 201
                  error:
                    description: Flag if there is an error in response. *False* for this response.
                    type: boolean
                    example: false
                  user:
                    description: The id of the user.
                    type: string
                    example: Ugr0xjYMS9y0eN5gBxSSmg
                  active:
                    description: Account status
                    type: boolean
                    example: true
                  email:
                    description: The email of the user for whom we want the auth token.
                    type: string
                    example: joe@foo.com
                  extra:
                    description: A JSON object with extra data about the user.
                    type: object
                    example: {}
                  tenant:
                    description: The name of the tenant for whose user we want the auth token.
                    type: string
                    example: foo
                  displayName:
                    description: The name of the user for whom we want the auth token.
                    type: string
                    example: joe
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '400':
          description: Failed due to missing or malformed data. Verify that all parameters are complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_400'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '401':
          description: Failed to validate because you do not have access to the GeoFabric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_401'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '403':
          description: Failed to validate because you do not have access to the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_403'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '409':
          description: Failed because user already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_409'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
      summary: Create User
      tags:
      - Users
  /_api/user/:
    get:
      description: Fetch data about all users.
      operationId: ListAvailableUsers
      responses:
        '200':
          description: Successfully fetched all users.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    description: HTTP response code.
                    type: integer
                    example: 200
                  error:
                    description: Flag if there is an error in response. *False* for this response.
                    type: boolean
                    example: false
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        tenant:
                          description: The name of the tenant.
                          type: string
                          example: _mm
                        user:
                          description: The id of the user.
                          type: string
                          example: Ugr0xjYMS9y0eN5gBxSSmg
                        displayName:
                          description: The username of the tenant.
                          type: string
                          example: test1
                        email:
                          description: The email of the user.
                          type: string
                          example: test@foo.com
                        active:
                          description: (Optional) If set to *true*, the user is active.
                          type: boolean
                          default: true
                        apikey:
                          description: Hash of API key.
                          type: object
                          properties:
                            hash:
                              description: Hash of API key.
                              type: string
                              example: 1467ad2eed8e823f5a5db74aacd716d2f87dc3dde2bced8799e3c07dcf1c88ee
                            parent:
                              description: Hash of API key.
                              type: string
                              example: ''
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '400':
          description: Failed due to missing or malformed data. Verify that all parameters are complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_400'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '401':
          description: Failed to validate because you do not have access to the GeoFabric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_401'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '403':
          description: Failed to validate because you do not have access to the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_403'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
      summary: List available Users
      tags:
      - Users
  /_api/user/{user}:
    delete:
      description: 'Remove an existing user.


        **Note**: Requires *administrator* permissions.'
      operationId: RemoveUser
      parameters:
      - description: The id of the user.
        in: path
        name: user
        required: true
        schema:
          type: string
          format: string
      responses:
        '202':
          description: Successfully removed user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    description: HTTP response code.
                    type: integer
                    example: 202
                  error:
                    description: Flag if there is an error in response. *False* for this response.
                    type: boolean
                    example: false
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '400':
          description: Failed due to missing or malformed data. Verify that all parameters are complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_400'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '401':
          description: Failed to validate because you do not have access to the GeoFabric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_401'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '403':
          description: Failed to validate because you do not have access to the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_403'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '404':
          description: Failed to find specified user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_404'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
      summary: Remove User
      tags:
      - Users
    get:
      description: 'Fetch data about the specified user.


        **Note**: Requires *administrator* permissions to access other users data.'
      operationId: FetchUser
      parameters:
      - description: The id of the user.
        in: path
        name: user
        required: true
        schema:
          type: string
          format: string
      responses:
        '200':
          description: Successfully fetched data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_key_http_examples_rc_200_0'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '400':
          description: Failed due to missing or malformed data. Verify that all parameters are complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_400'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '401':
          description: Failed to validate because you do not have access to the GeoFabric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_401'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '403':
          description: Failed to validate because you do not have access to the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_403'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '404':
          description: Failed to find specified user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_404'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
      summary: Fetch User
      tags:
      - Users
    patch:
      description: 'Update the data of an existing user.


        **Note**: Requires *administrator* permissions if changing the email address.'
      operationId: ModifyUser
      parameters:
      - description: The id of the user.
        in: path
        name: user
        required: true
        schema:
          type: string
          format: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/user_modify'
        required: true
      responses:
        '200':
          description: Successfully modified user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_key_http_examples_rc_200_0'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '400':
          description: Failed due to missing or malformed data. Verify that all parameters are complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_400'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '401':
          description: Failed to validate because you do not have access to the GeoFabric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_401'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '403':
          description: Failed to validate because you do not have access to the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_403'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '404':
          description: Failed to find specified user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_404'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
      summary: Modify User.
      tags:
      - Users
  /_api/user/{user}/database:
    get:
      description: 'Fetch the list of GeoFabrics available.


        The *result* object contains the GeoFabric names as object keys and the associated privileges for the GeoFabric as values.


        In case *full* is specified, the result contains the permissions for the GeoFabric as well as the permissions for the collections and streams.


        **Note**: Requires *administrator* permissions.'
      operationId: ListTheAccessibleDatabasesForAUser
      parameters:
      - description: The id of the user for which you want to query the databases.
        in: path
        name: user
        required: true
        schema:
          type: string
          format: string
      - description: Return the full set of access levels for all GeoFabrics and all collections.
        in: query
        name: full
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successfully fetched list of GeoFabrics.
          content:
            application/json:
              schema:
                example:
                  code: 200
                  error: false
                  result:
                    test: rw
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '400':
          description: Failed due to missing or malformed data. Verify that all parameters are complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_400'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '401':
          description: Failed to validate because you do not have access to the GeoFabric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_401'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '403':
          description: Failed to validate because you do not have access to the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_403'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
      summary: List the GeoFabrics available to user.
      tags:
      - Users
  /_api/user/{user}/database/{geofabric}:
    get:
      description: Fetch the access level for a specific GeoFabric.
      operationId: GetTheDatabaseAccessLevel
      parameters:
      - description: The id of the user for which you want to query the GeoFabric.
        in: path
        name: user
        required: true
        schema:
          type: string
          format: string
      - description: The name of the GeoFabric to query.
        in: path
        name: geofabric
        required: true
        schema:
          type: string
          format: string
          default: _system
      responses:
        '200':
          description: Successfully fetched GeoFabric access level.
          content:
            application/json:
              schema:
                example:
                  code: 200
                  error: false
                  result: rw
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '400':
          description: Failed due to missing or malformed data. Verify that all parameters are complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_400'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '401':
          description: Failed to validate because you do not have access to the GeoFabric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_401'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '403':
          description: Failed to validate because you do not have access to the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_403'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
      summary: Get the GeoFabric access level.
      tags:
      - Users
    delete:
      description: 'Clear the access level for the GeoFabric *geoname* of user *user*. As consequence the default GeoFabric access level is used. If there is no defined default GeoFabric access level, it defaults to *No access*.


        **Note**: Requires *administrator* permissions.'
      operationId: ClearTheDatabaseAccessLevel
      parameters:
      - description: The id of the user.
        in: path
        name: user
        required: true
        schema:
          type: string
          format: string
      - description: The name of the database.
        in: path
        name: geofabric
        required: true
        schema:
          type: string
          format: string
          default: _system
      responses:
        '202':
          description: Successfully cleared GeoFabric access level.
          content:
            application/json:
              schema:
                example:
                  code: 202
                  error: false
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '400':
          description: Failed due to missing or malformed data. Verify that all parameters are complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_400'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
      summary: Clear the GeoFabric access level
      tags:
      - Users
    put:
      description: 'Set the access levels for the GeoFabric *geoname* of user *user*.


        **Note**: Requires *administrator* permissions.'
      operationId: SetTheDatabaseAccessLevel
      parameters:
      - description: The id of the user.
        in: path
        name: user
        required: true
        schema:
          type: string
          format: string
      - description: The name of the GeoFabric.
        in: path
        name: geofabric
        required: true
        schema:
          type: string
          format: string
          default: _system
      requestBody:
        $ref: '#/components/requestBodies/user_grant_database'
      responses:
        '200':
          description: Successfully set GeoFabric access level.
          content:
            application/json:
              schema:
                example:
                  code: 200
                  error: false
                  testgeo: ro
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '400':
          description: Failed due to missing or malformed data. Verify that all parameters are complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_400'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '401':
          description: Failed to validate because you do not have access to the GeoFabric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_401'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '403':
          description: Failed to validate because you do not have access to the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_403'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
      summary: Set the GeoFabric access level
      tags:
      - Users
  /_api/user/{user}/database/{geofabric}/collection:
    get:
      description: "Fetch the list of collections access level for a specific *user*\n\n If access level for collection is not set default(\"*\") access level is used. If default(\"*\") access level is also not set GeoFabric access level is used."
      operationId: GetTheAllCollectionAccessLevel
      parameters:
      - description: The id of the user for which you want to query the GeoFabric.
        in: path
        name: user
        required: true
        schema:
          type: string
          format: string
      - description: The name of the GeoFabric to query.
        in: path
        name: geofabric
        required: true
        schema:
          type: string
          format: string
          default: _system
      - description: Return the full set of access levels for all collections.
        in: query
        name: full
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successfully fetched collections access level.
          content:
            application/json:
              schema:
                example:
                  error: false
                  code: 200
                  result:
                    testCollection: rw
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '400':
          description: Failed due to missing or malformed data. Verify that all parameters are complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_400'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '401':
          description: Failed to validate because you do not have access to the GeoFabric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_401'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '403':
          description: Failed to validate because you do not have access to the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_403'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
        '404':
          description: Failed to find specified fabric, user or collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_example_rc_404'
          headers:
            x-gdn-region:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-region'
            x-gdn-requestid:
              schema:
                $ref: '#/components/schemas/headers/x-gdn-requestid'
      summary: Get the collections access level for specific user
      tags:
      - Users
  /_api/user/{user}/database/{geofabric}/collection/{collection}:
    get:
      description: "Fetch the collection access level for a specific collection\n\n If access level for collection is not set default(\"*\") access level is used. If default(\"*\") access level is also not set GeoFabric 

# --- truncated at 32 KB (108 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/macrometa/refs/heads/main/openapi/macrometa-users-api-openapi.yml