v1
Double column
API
CLI
JS Client

Secrets /

Create secret

Creates a secret with the specified payload

Path parameters

    • projectId

      string required
      ID of the project

Request body

  • {object}
    • name

      string required
      The name of the secret.
      min length
      3
      max length
      100
      pattern
      ^[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*$
    • description

      string
      A description of the secret.
      max length
      200
      pattern
      ^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$
    • tags

      [array]
      An array of previously defined tags to help identify and group the resource.
      • string
        min length
        3
        max length
        100
        pattern
        ^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$
    • type

      string
      The hierarchy type of the created secret.
      one of
      secret, config
    • secretType

      string required
      The injection scope of the created secret
      one of
      environment-arguments, environment, arguments
    • priority

      integer required
      The priority with which different secrets will be merged.
      min
      0
      max
      100
    • restrictions

      {object}
      Restriction settings of the secret
      • restricted

        boolean
        Whether the secret is restricted to specific resources. If this is `true`, only resources listed in `nfObjects` or with a tag listed in `tags` will have access to these secrets. Otherwise, all resources in the project will be able to access it.
      • nfObjects

        [array]
        List of Northflank services & jobs the secret is restricted to
        • {object}
          • id

            string required
            ID of the entity the secret is restricted to.
            pattern
            ^[A-Za-z0-9-]+$
          • type

            string required
            Type of the entity the secret is restricted to.
            one of
            service, job
      • tags

        [array]
        List of tags the secret is restricted to.
        • string
          min length
          3
          max length
          100
          pattern
          ^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$
      • tagMatchCondition

        string
        If all or any of the tags must be present on the target for it to match the condition.
        one of
        and, or
    • addonDependencies

      [array]
      An array of addons to link to this secret group.
      • {object}
        An object containing data about the addon to link.
        • addonId

          string required
          The id of the addon to link.
          pattern
          ^[A-Za-z0-9-]+$
        • keys

          [array] required
          An array of objects containing details about the keys to link to this secret group.
          • {object}
            Details about the key to link to this secret group.
            • keyName

              string required
              The name of the key to link.
              pattern
              [a-zA-Z]+
            • aliases

              [array]
              An array of aliases for the key.
              • string
                The name of the alias. Keys may only contain letters, numbers, hyphens, forward slashes and dots.
                pattern
                ^[a-zA-Z0-9_./-]*$
    • secrets

      {object}
      • variables

        {object}
        Secret variables as JSON object, encrypted at rest. Keys may only contain letters, numbers, hyphens, forward slashes and dots.
        • files

          {object}
          Secret files as JSON object, encrypted at rest. File path must be absolute
          • dockerSecretMounts

            {object}
            Docker secret mount contents as JSON object, encrypted at rest. Must be a valid Docker secret mount identifier

        Response body

        • {object}
          Response object.
          • data

            {object} required
            Result data.
            • name

              string required
              The name of the secret.
              min length
              3
              max length
              100
              pattern
              ^[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*$
            • description

              string
              A description of the secret.
              max length
              200
              pattern
              ^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$
            • tags

              [array]
              An array of previously defined tags to help identify and group the resource.
              • string
                min length
                3
                max length
                100
                pattern
                ^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$
            • type

              string
              The hierarchy type of the created secret.
              one of
              secret, config
            • secretType

              string required
              The injection scope of the created secret
              one of
              environment-arguments, environment, arguments
            • priority

              integer required
              The priority with which different secrets will be merged.
              min
              0
              max
              100
            • restrictions

              {object}
              Restriction settings of the secret
              • restricted

                boolean
                Whether the secret is restricted to specific resources. If this is `true`, only resources listed in `nfObjects` or with a tag listed in `tags` will have access to these secrets. Otherwise, all resources in the project will be able to access it.
              • nfObjects

                [array]
                List of Northflank services & jobs the secret is restricted to
                • {object}
                  • id

                    string required
                    ID of the entity the secret is restricted to.
                    pattern
                    ^[A-Za-z0-9-]+$
                  • type

                    string required
                    Type of the entity the secret is restricted to.
                    one of
                    service, job
              • tags

                [array]
                List of tags the secret is restricted to.
                • string
                  min length
                  3
                  max length
                  100
                  pattern
                  ^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$
              • tagMatchCondition

                string
                If all or any of the tags must be present on the target for it to match the condition.
                one of
                and, or
            • addonDependencies

              [array]
              An array of addons to link to this secret group.
              • {object}
                An object containing data about the addon to link.
                • addonId

                  string required
                  The id of the addon to link.
                  pattern
                  ^[A-Za-z0-9-]+$
                • keys

                  [array] required
                  An array of objects containing details about the keys to link to this secret group.
                  • {object}
                    Details about the key to link to this secret group.
                    • keyName

                      string required
                      The name of the key to link.
                      pattern
                      [a-zA-Z]+
                    • aliases

                      [array]
                      An array of aliases for the key.
                      • string
                        The name of the alias. Keys may only contain letters, numbers, hyphens, forward slashes and dots.
                        pattern
                        ^[a-zA-Z0-9_./-]*$
            • secrets

              {object}
              • variables

                {object}
                Secret variables as JSON object, encrypted at rest. Keys may only contain letters, numbers, hyphens, forward slashes and dots.
                • files

                  {object}
                  Secret files as JSON object, encrypted at rest. File path must be absolute
                  • dockerSecretMounts

                    {object}
                    Docker secret mount contents as JSON object, encrypted at rest. Must be a valid Docker secret mount identifier
                  • id

                    string required
                    Identifier for the secret group
                    min length
                    3
                    max length
                    100
                    pattern
                    ^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$
                  • createdAt

                    string
                    time of creation
                  • updatedAt

                    string
                    time of update
              API
              CLI
              JS Client

              POST /v1/projects/{projectId}/secrets

              Example request

              Request body
              curl
              curl --header "Content-Type: application/json" \
                --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
                --request POST \
                --data '{"name":"Example Secret","description":"A description","type":"secret","secretType":"environment","priority":10,"restrictions":{"restricted":true,"nfObjects":[{"id":"example-service","type":"service"}],"tagMatchCondition":"or"},"addonDependencies":[{"addonId":"example-addon","keys":[{"keyName":"USERNAME","aliases":["MONGO_USERNAME"]}]}],"secrets":{"variables":{"NODE_ENV":"production","MONGO_DB":"some_connection_string"},"files":{"/dir/fileName":{"data":"VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=","encoding":"utf-8"}},"dockerSecretMounts":{"example-secret-mount_1":{"data":"VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=","encoding":"utf-8"}}}}' \
                https://api.northflank.com/v1/projects/{projectId}/secrets

              Example response

              200 OK

              Details about the newly created secret.

              JSON

              {
                "data": {
                  "name": "Example Secret",
                  "description": "A description",
                  "type": "secret",
                  "secretType": "environment",
                  "priority": 10,
                  "restrictions": {
                    "restricted": true,
                    "nfObjects": [
                      {
                        "id": "example-service",
                        "type": "service"
                      }
                    ],
                    "tagMatchCondition": "or"
                  },
                  "addonDependencies": [
                    {
                      "addonId": "example-addon",
                      "keys": [
                        {
                          "keyName": "USERNAME",
                          "aliases": [
                            "MONGO_USERNAME"
                          ]
                        }
                      ]
                    }
                  ],
                  "secrets": {
                    "variables": {
                      "NODE_ENV": "production",
                      "MONGO_DB": "some_connection_string"
                    },
                    "files": {
                      "/dir/fileName": {
                        "data": "VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=",
                        "encoding": "utf-8"
                      }
                    },
                    "dockerSecretMounts": {
                      "example-secret-mount_1": {
                        "data": "VGhpcyBpcyBhbiBleGFtcGxlIHdpdGggYSB0ZW1wbGF0ZWQgJHtOT0RFX0VOVn0gdmFyaWFibGU=",
                        "encoding": "utf-8"
                      }
                    }
                  },
                  "id": "example-secret-group"
                }
              }

              Example response

              409 Conflict

              There is already a secret with the same derived identifier

              © 2025 Northflank Ltd. All rights reserved.