Macrometa API key API

openapi: 3.0.0
info:
  title: Macrometa API Reference Activity Metrics API key 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: API key
paths:
  /api/vwr/v1/apikey:
    post:
      summary: Create a new API Key
      tags:
      - API key
      description: 'Create a new API key. Keep the API key safe, because it cannot be retrieved. Provide the TTL in days and specify the role of the API key.


        __The following roles are supported.__

        * admin - Can run all API endpoints.

        * editor - Can run all API endpoints, except API keys endpoints.

        * viewer - Can only run read API endpoints.


        This API requires _admin_ permissions to run.

        '
      operationId: createAPIKey
      security:
      - APIKeyAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/APIKey'
      responses:
        '202':
          description: Successfully create an API Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostAPIKeyResponse'
        '400':
          description: Bad request.
        '401':
          description: Authorization failure due to invalid authentication credentials.
        '403':
          description: Either the API key doesn't have permissions or it is deactivated.
        '409':
          description: Conflict _key_id_ already present.
        '500':
          description: Internal server error.
    get:
      summary: Get API keys details
      tags:
      - API key
      description: Gets all API key details.
      operationId: getAPIKeysDetails
      security:
      - APIKeyAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        description: The _limit_ parameter determines the number of API keys returned.
        schema:
          type: number
          minimum: 1
          maximum: 1000
          default: 1000
      - name: offset
        in: query
        required: false
        description: Represents the starting point from where to begin fetching the API key records. This parameter is especially useful in conjunction with the _limit_ parameter for pagination of a large number of API key records. By default, it is set to 0, meaning that data retrieval will start from the very first record. For example, if you have 10,000 API key records and set the _limit_ to 100, then the first API call without an offset will retrieve records 1 to 100. If you set the _offset_ to 100 for the next call, you will retrieve records 101 to 200, and so on. This way, by incrementing the _offset_ by the _limit_ value for successive calls, you can paginate through the entire dataset.
        schema:
          type: number
          default: 0
      - name: pattern
        in: query
        required: false
        description: Fetch API key information that matches the pattern. For example, a pattern could be 'aa' or 'test'. To get all API keys, set the pattern to '*'.
        schema:
          type: string
          default: '*'
      - name: sortby
        in: query
        required: false
        description: The field used for sorting.
        schema:
          type: string
          enum:
          - key_id
          - created_at
          - expire_at
          - ttl
          default: key_id
      - name: order
        in: query
        required: false
        description: "The sort order:\n * _asc_ - Ascending, from A to Z\n * _desc_ - Descending, from Z to A\n"
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      responses:
        '200':
          description: Successfully fetched all API keys.
          headers:
            X-count:
              description: The total number of records that match the pattern.
              schema:
                type: number
                default: 1000
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAPIKeysResponse'
        '401':
          description: Authorization failure due to invalid authentication credentials.
        '403':
          description: Either the API key doesn't have permissions or it is deactivated.
        '500':
          description: Internal server error.
  /api/vwr/v1/apikey/{key_id}:
    get:
      summary: Get API key by unique key_id
      tags:
      - API key
      description: Gets API key by unique key_id.
      operationId: getAPIKey
      security:
      - APIKeyAuth: []
      parameters:
      - name: key_id
        in: path
        description: A unique identifier for the API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully fetched the API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAPIKeyResponse'
        '400':
          description: Bad request.
        '401':
          description: Authorization failure due to invalid authentication credentials.
        '403':
          description: Either the API key doesn't have permissions or it is deactivated.
        '404':
          description: API key not found.
        '500':
          description: Internal server error.
    patch:
      summary: Update API key
      tags:
      - API key
      description: 'Update the activation status of the API key.


        This API requires _admin_ permissions to run.

        '
      operationId: updateAPIKey
      security:
      - APIKeyAuth: []
      parameters:
      - name: key_id
        in: path
        description: A unique identifier for the API key.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchAPIKey'
      responses:
        '200':
          description: Successfully update the API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchAPIKeyResponse'
        '400':
          description: Bad request.
        '401':
          description: Authorization failure due to invalid authentication credentials.
        '403':
          description: Either the API key doesn't have permissions or it is deactivated.
        '404':
          description: API Key not found.
        '500':
          description: Internal server error.
    delete:
      summary: Delete key
      tags:
      - API key
      description: 'Delete API key with a unique _key_id_.


        This API requires _admin_ permissions to run.

        '
      operationId: deleteKey
      security:
      - APIKeyAuth: []
      parameters:
      - name: key_id
        in: path
        description: A unique identifier for the API key.
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Successfuly deleted the API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthDeleteResponse'
        '403':
          description: Either the API key doesn't have permissions or it is deactivated.
        '404':
          description: API key Not found.
        '500':
          description: Internal server error.
components:
  schemas:
    AuthDeleteResponse:
      type: object
      properties:
        _key:
          type: string
        deleted_at:
          type: number
          format: number
          example: 1694757000
    PostAPIKeyResponse:
      type: object
      properties:
        key_id:
          type: string
          description: A unique identifier for the API key.
        api_key:
          type: string
          description: API key to authenticate with.
        role:
          description: The role of the API key.
          type: string
          enum:
          - editor
          - admin
          - viewer
          default: editor
          example: editor
        created_at:
          type: number
          format: number
          example: 1694757000
        expire_at:
          type: number
          format: number
          example: 1694767000
    APIKey:
      type: object
      required:
      - key_id
      properties:
        key_id:
          type: string
          description: A unique identifier for the API key.
        role:
          type: string
          description: The role of the API key. Supported Roles:[admin, editor, and viewer].
          default: editor
        ttl:
          type: number
          description: Time for which the API key will remain valid (in days).
          minimum: 1
          maximum: 180
          default: 180
        activated:
          type: boolean
          description: The activation status of the API key.
          default: true
    GetAPIKeyResponse:
      type: object
      properties:
        key_id:
          type: string
          description: A unique identifier for the API key.
          example: test_key
        activated:
          type: boolean
          description: True if API key is enabled.
          example: true
        expire_at:
          type: number
          description: The Unix timestamp, in seconds, when the API key expires.
          example: 1694767000
        created_at:
          type: number
          description: The Unix timestamp, in seconds, when the API key is created.
          format: number
          example: 1694757000
        role:
          type: string
          enum:
          - editor
          - admin
          - viewer
          description: The role of the API key.
          example: editor
        ttl:
          type: number
          description: Duration in days from creation that the API key stays valid.
          format: number
          example: 180
    PatchAPIKey:
      type: object
      required:
      - key_id
      properties:
        activated:
          type: boolean
          description: The activation status of the API key.
          default: true
    PatchAPIKeyResponse:
      type: object
      properties:
        key_id:
          type: string
          description: A unique identifier for the API key.
        updated_at:
          type: number
          format: number
          example: 1694757010
    GetAPIKeysResponse:
      type: array
      items:
        $ref: '#/components/schemas/GetAPIKeyResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Provide an API Key to the `Authorization` header, prefixed with "apikey".


        Example: `Authorization: apikey <key>`'
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Provide a JSON Web Token (JWT) to the `Authorization` header, prefixed with "bearer".


        Example: `Authorization: bearer <jwt>`'