CreateServicePrincipalKey
- 17 Sep 2026
- Print
- DarkLight
CreateServicePrincipalKey
- Updated on 17 Sep 2026
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Post
/v1/accounts/{accountId}/servicePrincipals/{servicePrincipalId}/keys
Availability
Early Access: July 1, 2026
Early Access is gated; contact the Backblaze Sales team for access.
Limited Availability: July 1, 2026
This API is available only to customers with access to the Backblaze Enterprise Web Console. For more information, contact the Backblaze Sales team.
Create a new API key for a Service Principal
The response includes a credentialId and secret for authentication. The secret is returned only in this response and cannot be retrieved later; callers must store it securely at creation time.
Either expireTime or ttl may be supplied to bound the key's lifetime. If both are provided, ttl is used to derive expireTime. If neither is set, the key does not expire.
ttl is input-only and is not returned. Format: protobuf Duration JSON, for example 3600s.
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
Body parameters
withExpireTime
With explicit expireTime
{
"displayName": "my-key",
"expireTime": "2026-12-31T23:59:59Z"
}withTtl
With TTL
{
"displayName": "my-key",
"ttl": "3600s"
}noExpiry
No expiration
{
"displayName": "my-key"
}object
displayName
string Required
Examplemy-key
expireTime
string (date-time)
Optional absolute expiration. Mutually exclusive with ttl for derivation purposes; if both are supplied, ttl is used to derive expireTime.
Example2026-12-31T23:59:59Z
ttl
string
Optional duration string in protobuf Duration JSON format (e.g. 3600s). Input-only; not returned in responses.
Pattern^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
Example3600s
Responses
200
The request succeeded. The credentialId and secret are returned here; the secret cannot be retrieved later.
{
"name": "accounts/942733365851/servicePrincipals/2/keys/019e6a8a-678e-7298-9167-4bd65df2f272",
"displayName": "my-key",
"credentialId": "bz_spk_AAAA0_Jywr8AAAAAAAAABwGfPoLG0nO0nEZ4NpErFtw",
"secret": "bz_spksec1__exampleSecretValue",
"expireTime": "2026-12-31T23:59:59Z",
"createTime": "2026-04-22T20:30:00Z",
"updateTime": "2026-04-22T20:30:00Z",
"disabled": false,
"etag": "BwXk9a2J8p0="
}object
name
string
Resource name in the form accounts//servicePrincipals//keys/.
Exampleaccounts/912345678901/servicePrincipals/123/keys/019e6a8a-678e-7298-9167-4bd65df2f272
displayName
string
Exampleprod deployer
expireTime
string (date-time)
Absolute expiration timestamp. If absent, the key does not expire.
Example2026-06-01T00:00:00Z
createTime
string (date-time)
Example2026-04-22T20:03:47Z
updateTime
string (date-time)
Example2026-04-22T20:03:47Z
disabled
boolean
When true, the key cannot mint new bearer tokens. Outstanding tokens remain valid until they expire.
Examplefalse
etag
string
Opaque concurrency token.
ExampleBwXk9a2J8p0=
credentialId
string
The credential ID used as the HTTP Basic username when calling /orgs/v1/authorize.
Examplebz_spk_AAAA0_Jywr8AAAAAAAAABwGfPoLG0nO0nEZ4NpErFtw
secret
string
The key secret. Returned only on creation and cannot be retrieved later.
Examplebz_spksec1__exampleSecretValue
400
The request was malformed or failed validation.
| HTTP Status | Code | Description |
|---|---|---|
| 400 | INVALID_ARGUMENT | One or more request parameters were invalid. |
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 Status | Code | Description |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, expired, or invalid bearer token. |
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 Status | Code | Description |
|---|---|---|
| 403 | FORBIDDEN | The authenticated principal lacks permission for this action. |
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 Status | Code | Description |
|---|---|---|
| 409 | CONFLICT | etag mismatch, resource already exists, or precondition failed. |
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 Status | Code | Description |
|---|---|---|
| 429 | TOO_MANY_REQUESTS | Rate limit exceeded. Use exponential backoff. |
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 Status | Code | Description |
|---|---|---|
| 500 | INTERNAL | Unexpected server error. Include the requestId when contacting support. |
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?