Contents x
UpdateAccessRestrictionConfig
  • 17 Sep 2026
  • Print
  • Dark
    Light
Contents

UpdateAccessRestrictionConfig

  • Updated on 17 Sep 2026
  • 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