openapi: 3.0.0
info:
  title: envbee API reference
  version: 1.0.0
  description: >
    # Authentication


    We support two types of authentication mechanisms:


    ### API Key and Secret


    To authenticate with your application environment, provide its API key and
    secret as HTTP headers:

    - `x-api-key`

    - `x-api-secret`


    ### HMAC (Hash-based Message Authentication Code)


    The HMAC signature is 4 parts (1 part optional) joined without a seperator.


    | Part          | Required  | Example                          |
    Description                                 |

    | ------------- | --------- | -------------------------------- |
    ------------------------------------------- |

    | Unix          | Timestamp | Yes                              |
    1573504737300 | The current unix timestamp  |

    | Verb          | Yes       | POST                             | The verb of
    the request you are making      |

    | Route         | Yes       | /api/order                       | The route
    you are requesting                |

    | MD5 JSON Body | No        | 9bb58f26192e4ba00f01e2e7b136bbd8 | The MD5 of
    your JSON.stringify request body |


    The header format is:

    - `Authorization`: `HMAC <timestamp>:<signature>`


    `<timestamp>` is the current Unix timestamp, and `<signature>` is the HMAC
    hash of the timestamp, request method, URL path, and payload, signed using
    your `API_SECRET`.


    More information can be found in:
    https://www.npmjs.com/package/hmac-auth-express


    #### Example: Python HMAC Authentication


    ```python

    import hashlib

    import hmac

    import json

    import time


    api_secret = b"your_api_secret"

    hmac_obj = hmac.new(api_secret, digestmod=hashlib.sha256)

    current_time = str(int(time.time() * 1000))


    hmac_obj.update(current_time.encode("utf-8"))

    hmac_obj.update(b"GET")

    url_path = "/resource"

    hmac_obj.update(url_path.encode("utf-8"))


    content = json.dumps({}).encode("utf-8")

    content_hash = hashlib.md5(content).hexdigest()

    hmac_obj.update(content_hash.encode("utf-8"))


    auth_header = f"HMAC {current_time}:{hmac_obj.hexdigest()}"

    print("Authorization Header:", auth_header)

    ```
  contact:
    email: support@envbee.dev
    url: https://envbee.dev/
servers:
  - url: https://api.envbee.dev
    description: Production Environment
  - url: https://api-test.envbee.dev
    description: Staging Environment
tags:
  - name: Variables
    description: Manage application variables.
  - name: Variables values
    description: Retrieve specific values for your variables.
  - name: System
    description: >-
      Endpoints related to system monitoring and operational status, including
      health checks and other administrative operations.
paths:
  /v1/variables:
    get:
      tags:
        - Variables
      summary: Get variables
      description: Gets all variables for the calling application environment.
      security:
        - ApiKeyAuth: []
          ApiSecretAuth: []
        - HMACAuth: []
      parameters:
        - name: limit
          in: query
          description: The limit for pagination
          required: false
          schema:
            type: number
            minimum: 1
            default: 50
        - name: offset
          in: query
          description: The offset for pagination
          required: false
          schema:
            type: number
            minimum: 0
            default: 0
      responses:
        '200':
          $ref: '#/components/responses/VariablesListResponse'
        '400':
          $ref: '#/components/responses/BasicError'
        '401':
          $ref: '#/components/responses/BasicError'
        '404':
          $ref: '#/components/responses/BasicError'
      x-code-samples:
        - lang: Shell
          source: |
            curl -X GET https://api.envbee.dev/v1/variables \
              -H 'Accept: application/json' \
              -H 'x-api-key: YOUR_ENVBEE_API_KEY' \
              -H 'x-api-secret: YOUR_ENVBEE_API_SECRET'
        - lang: Python
          label: Python Example using requests
          source: >
            # Python Example using requests

            import requests

            api_key = "YOUR_ENVBEE_API_KEY"

            api_secret = b"YOUR_ENVBEE_API_SECRET"

            content = requests.get("https://api.envbee.dev/v1/variables",
            headers={"x-api-key": api_key, "x-api-secret": api_secret})

            print(content.json())
        - lang: Python
          label: Python Example using SDK
          source: |
            # Python Example using SDK
            from envbee_sdk import Envbee
            # Envbee class uses HMAC security
            eb = Envbee("YOUR_ENVBEE_API_KEY", b"YOUR_ENVBEE_API_SECRET")
            for v in eb.get_variables():
              print(v)
        - lang: Javascript
          label: Node.js Example using SDK
          source: |
            const envbeeInit = require("envbee-sdk");
            const envbee = envbeeInit({
              key: "YOUR_ENVBEE_API_KEY",
              secret: "YOUR_ENVBEE_API_SECRET"
            });
            const allVariables = await envbee.getVariables();
  /v1/variables/{id}:
    get:
      tags:
        - Variables
      summary: Get variable by id
      description: Get complete variable content by its id
      security:
        - ApiKeyAuth: []
          ApiSecretAuth: []
        - HMACAuth: []
      parameters:
        - name: id
          in: path
          description: The ID of the variable
          required: true
          schema:
            type: number
      responses:
        '200':
          $ref: '#/components/responses/VariableResponse'
        '400':
          $ref: '#/components/responses/BasicError'
        '401':
          $ref: '#/components/responses/BasicError'
        '404':
          $ref: '#/components/responses/BasicError'
      x-code-samples:
        - lang: Shell
          source: |
            curl -X GET https://api.envbee.dev/v1/variables/1 \
              -H 'Accept: application/json' \
              -H 'x-api-key: YOUR_ENVBEE_API_KEY' \
              -H 'x-api-secret: YOUR_ENVBEE_API_SECRET'
        - lang: Python
          label: Python Example using requests
          source: >
            # Python Example using requests

            import requests

            api_key = "YOUR_ENVBEE_API_KEY"

            api_secret = b"YOUR_ENVBEE_API_SECRET"

            content = requests.get("https://api.envbee.dev/v1/variables/1",
            headers={"x-api-key": api_key, "x-api-secret": api_secret})

            print(content.json())
        - lang: Python
          label: Python Example using SDK
          source: SDK does not include this endpoint
        - lang: Javascript
          label: Node.js Example using SDK
          source: SDK does not include this endpoint
  /v1/variables-values:
    get:
      tags:
        - Variables values
      summary: Get variables values
      description: Gets all variables values for the calling application environment.
      security:
        - ApiKeyAuth: []
          ApiSecretAuth: []
        - HMACAuth: []
      parameters:
        - name: limit
          in: query
          description: The limit for pagination
          required: false
          schema:
            type: number
            minimum: 1
            default: 50
        - name: offset
          in: query
          description: The offset for pagination
          required: false
          schema:
            type: number
            minimum: 0
            default: 0
      responses:
        '200':
          $ref: '#/components/responses/VariablesValuesListResponse'
        '400':
          $ref: '#/components/responses/BasicError'
        '401':
          $ref: '#/components/responses/BasicError'
        '404':
          $ref: '#/components/responses/BasicError'
      x-code-samples:
        - lang: Shell
          source: |
            curl -X GET https://api.envbee.dev/v1/variables-values \
              -H 'Accept: application/json' \
              -H 'x-api-key: YOUR_ENVBEE_API_KEY' \
              -H 'x-api-secret: YOUR_ENVBEE_API_SECRET'
        - lang: Python
          label: Python Example using requests
          source: >
            # Python Example using requests

            import requests

            api_key = "YOUR_ENVBEE_API_KEY"

            api_secret = b"YOUR_ENVBEE_API_SECRET"

            content = requests.get("https://api.envbee.dev/v1/variables-values",
            headers={"x-api-key": api_key, "x-api-secret": api_secret})

            print(content.json())
        - lang: Python
          label: Python Example using SDK
          source: SDK does not include this endpoint
        - lang: Javascript
          label: Node.js Example using SDK
          source: SDK does not include this endpoint
  /v1/variables-values/{id}:
    get:
      tags:
        - Variables values
      summary: Get variable value by id
      description: Get complete variable value content by its id
      security:
        - ApiKeyAuth: []
          ApiSecretAuth: []
        - HMACAuth: []
      parameters:
        - name: id
          in: path
          description: The ID of the variable value
          required: true
          schema:
            type: number
      responses:
        '200':
          $ref: '#/components/responses/VariableValueResponse'
        '400':
          $ref: '#/components/responses/BasicError'
        '401':
          $ref: '#/components/responses/BasicError'
        '404':
          $ref: '#/components/responses/BasicError'
      x-code-samples:
        - lang: Shell
          source: |
            curl -X GET https://api.envbee.dev/v1/variables-values/1 \
              -H 'Accept: application/json' \
              -H 'x-api-key: YOUR_ENVBEE_API_KEY' \
              -H 'x-api-secret: YOUR_ENVBEE_API_SECRET'
        - lang: Python
          label: Python Example using requests
          source: >
            # Python Example using requests

            import requests

            api_key = "YOUR_ENVBEE_API_KEY"

            api_secret = b"YOUR_ENVBEE_API_SECRET"

            content =
            requests.get("https://api.envbee.dev/v1/variables-values/1",
            headers={"x-api-key": api_key, "x-api-secret": api_secret})

            print(content.json())
        - lang: Python
          label: Python Example using SDK
          source: SDK does not include this endpoint
        - lang: Javascript
          label: Node.js Example using SDK
          source: SDK does not include this endpoint
  /v1/variables-values-by-name/{variable_name}:
    get:
      tags:
        - Variables values
      summary: Get variable value by name
      description: Get a variable's value by name
      security:
        - ApiKeyAuth: []
          ApiSecretAuth: []
        - HMACAuth: []
      parameters:
        - name: variable_name
          in: path
          description: The name of the variable
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VariableValueResponse'
        '400':
          $ref: '#/components/responses/BasicError'
        '401':
          $ref: '#/components/responses/BasicError'
        '404':
          $ref: '#/components/responses/BasicError'
      x-code-samples:
        - lang: Shell
          source: >
            curl -X GET
            https://api.envbee.dev/v1/variables-values-by-name/MyVar1 \
              -H 'Accept: application/json' \
              -H 'x-api-key: YOUR_ENVBEE_API_KEY' \
              -H 'x-api-secret: YOUR_ENVBEE_API_SECRET'
        - lang: Python
          label: Python Example using requests
          source: >
            # Python Example using requests

            import requests

            api_key = "YOUR_ENVBEE_API_KEY"

            api_secret = b"YOUR_ENVBEE_API_SECRET"

            content =
            requests.get("https://api.envbee.dev/v1/variables-values-by-name/MyVar1",
            headers={"x-api-key": api_key, "x-api-secret": api_secret})

            print(content.json())
        - lang: Python
          label: Python Example using SDK
          source: SDK does not include this endpoint
        - lang: Javascript
          label: Node.js Example using SDK
          source: SDK does not include this endpoint
  /v1/variables-values-by-name/{variable_name}/content:
    get:
      tags:
        - Variables values
      summary: Get variable value content by name
      description: Get a variable's value content by name
      security:
        - ApiKeyAuth: []
          ApiSecretAuth: []
        - HMACAuth: []
      parameters:
        - name: variable_name
          in: path
          description: The name of the variable
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VariableValueContentResponse'
        '400':
          $ref: '#/components/responses/BasicError'
        '401':
          $ref: '#/components/responses/BasicError'
        '404':
          $ref: '#/components/responses/BasicError'
      x-code-samples:
        - lang: Shell
          source: >
            curl -X GET
            https://api.envbee.dev/v1/variables-values-by-name/MyVar1/content \
              -H 'Accept: application/json' \
              -H 'x-api-key: YOUR_ENVBEE_API_KEY' \
              -H 'x-api-secret: YOUR_ENVBEE_API_SECRET'
        - lang: Python
          label: Python Example using requests
          source: >
            # Python Example using requests

            import requests

            api_key = "YOUR_ENVBEE_API_KEY"

            api_secret = b"YOUR_ENVBEE_API_SECRET"

            content =
            requests.get("https://api.envbee.dev/v1/variables-values-by-name/MyVar1/content",
            headers={"x-api-key": api_key, "x-api-secret": api_secret})

            print(content.json())
        - lang: Python
          label: Python Example using SDK
          source: |
            # Python Example using SDK
            from envbee_sdk import Envbee
            # Envbee class uses HMAC security
            eb = Envbee("YOUR_ENVBEE_API_KEY", b"YOUR_ENVBEE_API_SECRET")
            my_var = eb.get("MyVar1"):
            print(my_var)
        - lang: Javascript
          label: Node.js Example using SDK
          source: |
            const envbeeInit = require("envbee-sdk");
            const envbee = envbeeInit({
              key: "YOUR_ENVBEE_API_KEY",
              secret: "YOUR_ENVBEE_API_SECRET"
            });
            const databaseHost = await envbee.get("MyVar1");
  /healthz:
    get:
      tags:
        - System
      summary: Check application health status
      description: >-
        Returns the application uptime, a status message, and the current date
        and time.
      security: []
      responses:
        '200':
          description: Current health status of the application.
          content:
            application/json:
              schema:
                type: object
                properties:
                  uptime:
                    type: number
                    description: The application's uptime in seconds.
                    example: 46270.6011732
                  message:
                    type: string
                    description: A message indicating the application's health status.
                    example: Ok
                  date:
                    type: string
                    format: date-time
                    description: The current date and time in ISO 8601 format.
                    example: '2024-12-15T14:50:20.436Z'
      x-code-samples:
        - lang: Shell
          source: |
            curl -X GET https://api.envbee.dev/healthz \
              -H 'Accept: application/json'
security:
  - ApiKeyAuth: []
    ApiSecretAuth: []
  - HMACAuth: []
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
    Metadata:
      type: object
      description: JSON object that contains pagination data
      properties:
        limit:
          type: integer
          example: 1
        offset:
          type: integer
          example: 10
        total:
          type: integer
          example: 100
    Variable:
      type: object
      properties:
        id:
          type: number
        type:
          type: string
          enum:
            - STRING
            - BOOLEAN
            - NUMBER
        name:
          type: string
        description:
          type: string
          nullable: true
      required:
        - id
        - type
        - name
    VariableValue:
      type: object
      properties:
        id:
          type: number
        variable_id:
          type: number
        content:
          $ref: '#/components/schemas/VariableValueContent'
      required:
        - id
        - variable_id
        - content
    VariableValueContent:
      type: object
      properties:
        value:
          oneOf:
            - type: string
            - type: boolean
            - type: number
      required:
        - value
  responses:
    BasicError:
      description: Basic error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    VariableResponse:
      description: A variable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Variable'
    VariableValueResponse:
      description: A variable's value
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VariableValue'
    VariableValueContentResponse:
      description: A variable's value content
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VariableValueContent'
    VariablesListResponse:
      description: List of variables
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                $ref: '#/components/schemas/Metadata'
              data:
                type: array
                items:
                  $ref: '#/components/schemas/Variable'
    VariablesValuesListResponse:
      description: List of variables values
      content:
        application/json:
          schema:
            type: object
            properties:
              metadata:
                $ref: '#/components/schemas/Metadata'
              data:
                type: array
                items:
                  $ref: '#/components/schemas/VariableValue'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Api Key to access specific application and environment
    ApiSecretAuth:
      type: apiKey
      in: header
      name: x-api-secret
      description: 'Api Key and Secret used in headers: `x-api-key` and `x-api-secret`'
    HMACAuth:
      type: http
      scheme: hmac
      description: |
        <br/>HMAC Autentication using `Authorization` header with format:
        `Authorization: "HMAC <timestamp>:<signature>"`.
