Contents x
UpdateAccessRestrictionConfig
    • Print
    • Dark
      Light
    Contents

    UpdateAccessRestrictionConfig

      • Print
      • Dark
        Light
      Article summary

      Patch
      /v1/accounts/{accountId}/servicePrincipals/{servicePrincipalId}/accessRestrictionConfig

      Availability

      Early Access: Planned; date not yet confirmed

      Early Access is gated; contact the Backblaze Sales team for access.

      Limited Availability: Planned; date not yet confirmed

      This API is available only to customers with access to the Backblaze Enterprise Web Console. For more information, contact the Backblaze Sales team.

      Update the access restriction configuration for a Service Principal

      Supported updateMask values:

      • ipRestriction - updates both child fields
      • ipRestriction.enforce - updates enforcement flag only
      • ipRestriction.allowedCidrRanges - replaces the entire list of allowed ranges

      Semantics

      • Updating ipRestriction.allowedCidrRanges replaces the entire list. Supplying an empty list removes all entries.
      • At most 250 CIDR entries may be configured.
      • If enforcement is enabled while allowedCidrRanges is empty, all authentication requests for that Service Principal are denied.
      • name, etag, and updateTime may be included in PATCH bodies for compatibility but are ignored.
      • A service principal cannot enable IP restrictions that would block the source IP address of the current request. Other authorized callers may configure restrictions that prevent that service principal from authenticating, including configurations that deny all access.
      • CIDR entries are normalized before being returned. Examples: 192.0.2.10 → 192.0.2.10/32; 2001:db8::1 → 2001:db8::1/128; 192.0.2.10/24 → 192.0.2.0/24.
      Security
      HTTP
      Type bearer

      Short-lived bearer token obtained from GET /orgs/v1/authorize. Sent as Authorization - Bearer .

      Path parameters
      accountId
      stringRequired

      The numeric identifier of the account. Valid account IDs match 9[0-4][0-9]{10}.

      Pattern^9[0-4][0-9]{10}$
      Example912345678901
      servicePrincipalId
      stringRequired

      The identifier of the service principal.

      Pattern^[a-z0-9_-]{8,64}$
      Examplesp-control-plane
      Query parameters
      updateMask
      string

      Comma-separated list of fields to update. Supported values - ipRestriction, ipRestriction.enforce, ipRestriction.allowedCidrRanges. If omitted, all fields present in the request body are updated.

      ExampleipRestriction
      Body parameters
      {
  "ipRestriction": {
    "enforce": true,
    "allowedCidrRanges": [
      "192.0.2.0/24",
      "2001:db8::/48"
    ]
  }
}
      Expand All
      object
      ipRestriction
      object (IpRestriction)
      enforce
      boolean

      When false, the allowlist is stored but not applied during authentication. When true, authentication is allowed only from listed ranges; an empty list denies all authentication requests for the Service Principal.

      Exampletrue
      allowedCidrRanges
      Array of string

      Allowed source IP addresses and CIDR ranges. IPv4 and IPv6 are both supported. Maximum 250 entries. CIDR entries are normalized in responses.

      Max items250
      string
      Example192.0.2.0/24
      Responses
      200

      The request succeeded.

      {
  "name": "accounts/942733365851/servicePrincipals/2/accessRestrictionConfig",
  "ipRestriction": {
    "enforce": true,
    "allowedCidrRanges": [
      "192.0.2.0/24",
      "2001:db8::/48"
    ]
  },
  "etag": "CwYk3M1L9q2=",
  "updateTime": "2026-05-15T19:00:00Z"
}
      Expand All
      object
      name
      string
      Exampleaccounts/942733365851/servicePrincipals/2/accessRestrictionConfig
      ipRestriction
      object (IpRestriction)
      enforce
      boolean

      When false, the allowlist is stored but not applied during authentication. When true, authentication is allowed only from listed ranges; an empty list denies all authentication requests for the Service Principal.

      Exampletrue
      allowedCidrRanges
      Array of string

      Allowed source IP addresses and CIDR ranges. IPv4 and IPv6 are both supported. Maximum 250 entries. CIDR entries are normalized in responses.

      Max items250
      string
      Example192.0.2.0/24
      etag
      string
      ExampleBwXk9a2J8p0=
      updateTime
      string (date-time)
      400

      The request was malformed or failed validation.

      HTTP StatusCodeDescription
      400INVALID_ARGUMENTOne or more request parameters were invalid.
      Expand All
      object
      requestId
      string

      Opaque correlation identifier matching the Request-Id response header. Include in support requests.

      Example4bf92f3577b34da6a3ce929d0e0e4736
      error
      object
      code
      integer

      Numeric error code.

      Example10
      message
      string

      Human-readable description of the error.

      Exampleetag mismatch
      details
      object

      Reserved for structured, non-sensitive diagnostic information related to the error condition.

      401

      The request was not authenticated.

      HTTP StatusCodeDescription
      401UNAUTHORIZEDMissing, expired, or invalid bearer token.
      Expand All
      object
      requestId
      string

      Opaque correlation identifier matching the Request-Id response header. Include in support requests.

      Example4bf92f3577b34da6a3ce929d0e0e4736
      error
      object
      code
      integer

      Numeric error code.

      Example10
      message
      string

      Human-readable description of the error.

      Exampleetag mismatch
      details
      object

      Reserved for structured, non-sensitive diagnostic information related to the error condition.

      403

      The caller is not authorized to perform this operation.

      HTTP StatusCodeDescription
      403FORBIDDENThe authenticated principal lacks permission for this action.
      Expand All
      object
      requestId
      string

      Opaque correlation identifier matching the Request-Id response header. Include in support requests.

      Example4bf92f3577b34da6a3ce929d0e0e4736
      error
      object
      code
      integer

      Numeric error code.

      Example10
      message
      string

      Human-readable description of the error.

      Exampleetag mismatch
      details
      object

      Reserved for structured, non-sensitive diagnostic information related to the error condition.

      404

      The requested resource was not found.

      HTTP StatusCodeDescription
      404NOT_FOUNDThe resource does not exist or has been purged.
      Expand All
      object
      requestId
      string

      Opaque correlation identifier matching the Request-Id response header. Include in support requests.

      Example4bf92f3577b34da6a3ce929d0e0e4736
      error
      object
      code
      integer

      Numeric error code.

      Example10
      message
      string

      Human-readable description of the error.

      Exampleetag mismatch
      details
      object

      Reserved for structured, non-sensitive diagnostic information related to the error condition.

      409

      The request conflicted with the current state of the resource.

      HTTP StatusCodeDescription
      409CONFLICTetag mismatch, resource already exists, or precondition failed.
      Expand All
      object
      requestId
      string

      Opaque correlation identifier matching the Request-Id response header. Include in support requests.

      Example4bf92f3577b34da6a3ce929d0e0e4736
      error
      object
      code
      integer

      Numeric error code.

      Example10
      message
      string

      Human-readable description of the error.

      Exampleetag mismatch
      details
      object

      Reserved for structured, non-sensitive diagnostic information related to the error condition.

      429

      The request was rate-limited.

      HTTP StatusCodeDescription
      429TOO_MANY_REQUESTSRate limit exceeded. Use exponential backoff.
      Expand All
      object
      requestId
      string

      Opaque correlation identifier matching the Request-Id response header. Include in support requests.

      Example4bf92f3577b34da6a3ce929d0e0e4736
      error
      object
      code
      integer

      Numeric error code.

      Example10
      message
      string

      Human-readable description of the error.

      Exampleetag mismatch
      details
      object

      Reserved for structured, non-sensitive diagnostic information related to the error condition.

      500

      The server encountered an unexpected condition.

      HTTP StatusCodeDescription
      500INTERNALUnexpected server error. Include the requestId when contacting support.
      Expand All
      object
      requestId
      string

      Opaque correlation identifier matching the Request-Id response header. Include in support requests.

      Example4bf92f3577b34da6a3ce929d0e0e4736
      error
      object
      code
      integer

      Numeric error code.

      Example10
      message
      string

      Human-readable description of the error.

      Exampleetag mismatch
      details
      object

      Reserved for structured, non-sensitive diagnostic information related to the error condition.

      Was this article helpful?
      What's Next