Skip to content

Create a WAF

POST
https://waf-api.ezghcloud.com/v1/organizations/{orgId}/projects/{projectId}/wafs

Authorization

  • apiKeyoptionalHTTP
  • oauthoptionalHTTP
  • sessionCookieoptionalAPI key in cookie

Path parameters

  • orgIdstringrequired

    UUID or prefixed ID (org_…)

  • projectIdstringrequired

    UUID or prefixed ID (prj_…)

Header parameters

  • Idempotency-Keyoptionalstring

    Makes a retry safe: the same key and request get the stored response.

    pattern: ^[\x21-\x7e]{1,200}$

Request bodyJSONrequired

  • namestringrequired
    maxLength: 100, minLength: 1
  • defaultActionoptionalallow
  • descriptionoptionalstring | null
    maxLength: 500
  • loggingoptionalobject
    2 properties
    • environmentstring | nullrequired

      The Obs environment in the WAF's project; required unless scope is off. Turning logging on needs obs.logs.ingest on the project.

      pattern: ^[a-z0-9][a-z0-9._-]{0,62}$
    • scopeofformatchedorallrequired

      Request logs to Obs: none, the requests a rule matched, or every request.

  • managedRuleSetsoptionalarray ofobject
    4 properties
    • modeblockorlogrequired

      Default block.

    • nameezgh/coreorezgh/phporezgh/nodeorezgh/known-bad-inputsrequired
    • paranoiaLevelinteger | nullrequired

      ezgh/core only (default 1); null for the others.

      maximum: 2, minimum: 1
    • ruleOverridesarray ofobjectrequired
      2 properties
      • actionofforlogrequired
      • ruleIdintegerrequired

        A rule of the set.

  • modeoptionalblockorlog
  • rulesoptionalarray ofobject
    5 properties
    • actionalloworblockorlogorrateLimitrequired

      allow stops and skips the managed sets; block answers 403; log records and continues; rateLimit counts matching requests per client address and blocks (or logs) a client over the limit.

    • All must match.

      6 variants

      One of the following:

      • 3 properties
        • cidrsarray ofstringrequired

          IPv4 and IPv6 addresses and CIDR blocks.

        • negatebooleanrequired

          Match when the condition doesn't hold. Default false.

        • typeunknownrequired
      • 3 properties
        • negatebooleanrequired

          Match when the condition doesn't hold. Default false.

        • numbersarray ofintegerrequired
          maximum: 4294967295, minimum: 1
        • typeunknownrequired
      • 3 properties
        • codesarray ofstringrequired

          ISO 3166-1 alpha-2 codes.

          pattern: ^[A-Z]{2}$
        • negatebooleanrequired

          Match when the condition doesn't hold. Default false.

        • typeunknownrequired
      • 5 properties
        • caseSensitivebooleanrequired

          Default false.

        • negatebooleanrequired

          Match when the condition doesn't hold. Default false.

        • targetstringrequired

          path, query, method, body (the inspected part), header: or cookie:; a name is 1-64 letters, digits, - and _.

          pattern: ^(path|query|method|body|(header|cookie):[A-Za-z0-9_-]{1,64})$
        • typeunknownrequired
        • valuestringrequired

          At most 1,024 bytes.

          maxLength: 1024
      • 5 properties
        • caseSensitivebooleanrequired

          Default false.

        • negatebooleanrequired

          Match when the condition doesn't hold. Default false.

        • targetstringrequired

          path, query, method, body (the inspected part), header: or cookie:; a name is 1-64 letters, digits, - and _.

          pattern: ^(path|query|method|body|(header|cookie):[A-Za-z0-9_-]{1,64})$
        • typeunknownrequired
        • valuestringrequired

          At most 1,024 bytes.

          maxLength: 1024
      • 5 properties
        • caseSensitivebooleanrequired

          Default false.

        • negatebooleanrequired

          Match when the condition doesn't hold. Default false.

        • targetstringrequired

          path, query, method, body (the inspected part), header: or cookie:; a name is 1-64 letters, digits, - and _.

          pattern: ^(path|query|method|body|(header|cookie):[A-Za-z0-9_-]{1,64})$
        • typeunknownrequired
        • valuestringrequired

          At most 1,024 bytes.

          maxLength: 1024
    • modeblockorlogornullrequired

      rateLimit only (default block); null otherwise.

    • namestringrequired

      Unique in the WAF.

      pattern: ^[a-z0-9-]{1,64}$
    • rateLimitRateLimitornullrequired

      rateLimit only; null otherwise.

      2 variants

      One of the following:

  • tagsoptionalmap ofstring

    At most 50; keys 1-128 characters (ezgh: is reserved), values at most 256.

Returns

201

The WAF.

JSON
  • attachmentsarray ofstringrequired

    The load balancers (lbr_…) and CDN distributions (cdn_…) it's attached to. Attach on the load balancer or the distribution.

  • createdAtstringrequired
    format: date-time
  • defaultActionallowrequired
  • descriptionstring | nullrequired
  • idstringrequired
    format: uuid
  • loggingobjectrequired
    2 properties
    • environmentstring | nullrequired

      The Obs environment in the WAF's project; required unless scope is off. Turning logging on needs obs.logs.ingest on the project.

      pattern: ^[a-z0-9][a-z0-9._-]{0,62}$
    • scopeofformatchedorallrequired

      Request logs to Obs: none, the requests a rule matched, or every request.

  • managedRuleSetsarray ofobjectrequired

    Run in order, after the custom rules.

    4 properties
    • modeblockorlogrequired

      Default block.

    • nameezgh/coreorezgh/phporezgh/nodeorezgh/known-bad-inputsrequired
    • paranoiaLevelinteger | nullrequired

      ezgh/core only (default 1); null for the others.

      maximum: 2, minimum: 1
    • ruleOverridesarray ofobjectrequired
      2 properties
      • actionofforlogrequired
      • ruleIdintegerrequired

        A rule of the set.

  • modeblockorlogrequired

    log turns every block of the WAF into a log.

  • namestringrequired
  • organizationIdstringrequired
    format: uuid
  • projectIdstringrequired
    format: uuid
  • regionstringrequired
  • resourceNamestringrequired
  • rulesarray ofobjectrequired

    Custom rules, top to bottom; the first that ends a request wins.

    5 properties
    • actionalloworblockorlogorrateLimitrequired

      allow stops and skips the managed sets; block answers 403; log records and continues; rateLimit counts matching requests per client address and blocks (or logs) a client over the limit.

    • All must match.

      6 variants

      One of the following:

      • 3 properties
        • cidrsarray ofstringrequired

          IPv4 and IPv6 addresses and CIDR blocks.

        • negatebooleanrequired

          Match when the condition doesn't hold. Default false.

        • typeunknownrequired
      • 3 properties
        • negatebooleanrequired

          Match when the condition doesn't hold. Default false.

        • numbersarray ofintegerrequired
          maximum: 4294967295, minimum: 1
        • typeunknownrequired
      • 3 properties
        • codesarray ofstringrequired

          ISO 3166-1 alpha-2 codes.

          pattern: ^[A-Z]{2}$
        • negatebooleanrequired

          Match when the condition doesn't hold. Default false.

        • typeunknownrequired
      • 5 properties
        • caseSensitivebooleanrequired

          Default false.

        • negatebooleanrequired

          Match when the condition doesn't hold. Default false.

        • targetstringrequired

          path, query, method, body (the inspected part), header: or cookie:; a name is 1-64 letters, digits, - and _.

          pattern: ^(path|query|method|body|(header|cookie):[A-Za-z0-9_-]{1,64})$
        • typeunknownrequired
        • valuestringrequired

          At most 1,024 bytes.

          maxLength: 1024
      • 5 properties
        • caseSensitivebooleanrequired

          Default false.

        • negatebooleanrequired

          Match when the condition doesn't hold. Default false.

        • targetstringrequired

          path, query, method, body (the inspected part), header: or cookie:; a name is 1-64 letters, digits, - and _.

          pattern: ^(path|query|method|body|(header|cookie):[A-Za-z0-9_-]{1,64})$
        • typeunknownrequired
        • valuestringrequired

          At most 1,024 bytes.

          maxLength: 1024
      • 5 properties
        • caseSensitivebooleanrequired

          Default false.

        • negatebooleanrequired

          Match when the condition doesn't hold. Default false.

        • targetstringrequired

          path, query, method, body (the inspected part), header: or cookie:; a name is 1-64 letters, digits, - and _.

          pattern: ^(path|query|method|body|(header|cookie):[A-Za-z0-9_-]{1,64})$
        • typeunknownrequired
        • valuestringrequired

          At most 1,024 bytes.

          maxLength: 1024
    • modeblockorlogornullrequired

      rateLimit only (default block); null otherwise.

    • namestringrequired

      Unique in the WAF.

      pattern: ^[a-z0-9-]{1,64}$
    • rateLimitRateLimitornullrequired

      rateLimit only; null otherwise.

      2 variants

      One of the following:

  • slugstringrequired

    waf_…

  • statusstringrequired

    active; clients treat others as unknown.

  • tagsmap ofstringrequired

    At most 50; keys 1-128 characters (ezgh: is reserved), values at most 256.

  • updatedAtstringrequired
    format: date-time
  • versionintegerrequired

    Rises on every change; the ETag is its value in quotes.

400

invalid_request (with issues), invalid_cursor, or the endpoint's own 400 codes.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

401

unauthenticated: no credential, or one that doesn't check out.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

403

access_denied: the caller's policies don't allow the action; forbidden_origin: a cookie-authenticated write from an origin that isn't allowed; spend_limit_reached.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

404

not_found: unknown, malformed, or in an organization the caller isn't in.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

409

quota_exceeded (an allocation quota, with quota), idempotency_conflict, idempotency_in_progress (with Retry-After), organization_deletion_pending, operation_in_progress, or the endpoint's own 409 codes.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

413

payload_too_large: the body is over the endpoint's limit (1 MiB unless it says otherwise).

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

429

too_many_requests, with Retry-After; or quota_exceeded (a rate, usage or concurrency quota, with quota), never with Retry-After.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

500

internal_error: a bug; the details are in the logs, under the request ID.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

503

unavailable: a dependency the request needs is down. Retry after Retry-After.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close