Skip to content
Docs

Rotate an API key's signing secret

POST
/v2/api-keys/{id}/rotate-signing-secret
curl --request POST \
  --url https://api.connect.ms/v2/api-keys/example/rotate-signing-secret \
  --header 'Authorization: Bearer <token>'

Issues a new hmac_sha256 signing secret for the key, returned once in this response. The previous secret stops verifying shortly afterwards.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The id of the key.

Header Parameters

Section titled “Header Parameters”
Connect-Version
string

The API version to use, for example 2026-10-01. Defaults to the version set on your API key.

Idempotency-Key
string

A unique value of up to 255 characters, so a retried request is not acted on twice. Required for keys in Strict API Mode.

Responses

Section titled “Responses”

200

Section titled “200”

The key with its new signing secret.

Media typeapplication/json

An API key of the workspace.

object
id
required

The unique id of the key.

string
name

The display name of the key, or null.

string
nullable
keyPrefix
required

The first six characters of the key, for telling keys apart.

string
keyLast4
required

The last four characters of the key.

string
limits
required
One of:

The key’s SMS send limits and how much of them has been used.

object
dailyParts

The most SMS parts the key may send per UTC day. Null means unlimited.

integer format: int32
nullable
monthlyParts

The most SMS parts the key may send per UTC calendar month. Null means unlimited.

integer format: int32
nullable
usedToday
required

SMS parts counted against the key so far today (UTC), including parts reserved for sends being processed.

integer format: int32
usedThisMonth
required

SMS parts counted against the key so far this calendar month (UTC), including parts reserved for sends being processed.

integer format: int32
strictMode
required

True when every v2 request with this key must be signed and every POST or PATCH must carry an Idempotency-Key.

boolean
signing
One of:

How requests with the key are signed.

object
algorithm
required
One of:

The algorithm requests are signed with: hmac_sha256 (a shared secret issued by Connect) or ecdsa_p256_sha256 (your own P-256 key pair; you supply the public key).

string
Allowed values: hmac_sha256 ecdsa_p256_sha256
publicKey

The P-256 public key in SubjectPublicKeyInfo PEM format. Null for hmac_sha256.

string
nullable
apiVersion

The Connect-Version the key is pinned to. Null means it follows the current version.

string
nullable
createdAt
required

When (UTC) the key was created.

string format: date-time
activeFrom
required

When (UTC) the key becomes usable.

string format: date-time
expiresAt

When (UTC) the key stops working, or null when it does not expire. Set on a key that has been rotated.

string format: date-time
nullable
lastUsedAt

When (UTC) the key was last used. Not yet tracked, so always null.

string format: date-time
nullable
key

The full key. Only returned by the response that issued it (create and rotate); null everywhere else.

string
nullable
signingSecret

The hmac_sha256 signing secret. Only returned by create, rotate (which carries the existing secret over), rotate-signing-secret, or an update that switched the key to hmac_sha256; null everywhere else.

string
nullable

Example 

{
  "signing": {
    "algorithm": "hmac_sha256"
  }
}

400

Section titled “400”

The request is not valid, or the key does not sign with hmac_sha256 so there is no secret to rotate.

Media typeapplication/problem+json

Why a request failed, in the RFC 9457 problem details format.

object
type
required

A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.

string
title
required

A short, fixed summary of the kind of problem.

string
status
required

The HTTP status code of the response.

integer format: int32
detail

What went wrong with this particular request, when there is more to say than the title.

string
nullable
errors

For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).

object
key
additional properties
Array<string>
requestId
required

The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.

string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  },
  "requestId": "example"
}

401

Section titled “401”

The API key or bearer token is missing or not valid, or the request signature could not be verified.

Media typeapplication/problem+json

Why a request failed, in the RFC 9457 problem details format.

object
type
required

A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.

string
title
required

A short, fixed summary of the kind of problem.

string
status
required

The HTTP status code of the response.

integer format: int32
detail

What went wrong with this particular request, when there is more to say than the title.

string
nullable
errors

For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).

object
key
additional properties
Array<string>
requestId
required

The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.

string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  },
  "requestId": "example"
}

403

Section titled “403”

The caller is not allowed to do this.

Media typeapplication/problem+json

Why a request failed, in the RFC 9457 problem details format.

object
type
required

A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.

string
title
required

A short, fixed summary of the kind of problem.

string
status
required

The HTTP status code of the response.

integer format: int32
detail

What went wrong with this particular request, when there is more to say than the title.

string
nullable
errors

For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).

object
key
additional properties
Array<string>
requestId
required

The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.

string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  },
  "requestId": "example"
}

404

Section titled “404”

No API key with that id in this workspace.

Media typeapplication/problem+json

Why a request failed, in the RFC 9457 problem details format.

object
type
required

A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.

string
title
required

A short, fixed summary of the kind of problem.

string
status
required

The HTTP status code of the response.

integer format: int32
detail

What went wrong with this particular request, when there is more to say than the title.

string
nullable
errors

For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).

object
key
additional properties
Array<string>
requestId
required

The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.

string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  },
  "requestId": "example"
}

409

Section titled “409”

A request with this Idempotency-Key is still being processed. Retry after the Retry-After header.

Media typeapplication/problem+json

Why a request failed, in the RFC 9457 problem details format.

object
type
required

A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.

string
title
required

A short, fixed summary of the kind of problem.

string
status
required

The HTTP status code of the response.

integer format: int32
detail

What went wrong with this particular request, when there is more to say than the title.

string
nullable
errors

For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).

object
key
additional properties
Array<string>
requestId
required

The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.

string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  },
  "requestId": "example"
}

422

Section titled “422”

This Idempotency-Key was already used for a different request. Use a new key.

Media typeapplication/problem+json

Why a request failed, in the RFC 9457 problem details format.

object
type
required

A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.

string
title
required

A short, fixed summary of the kind of problem.

string
status
required

The HTTP status code of the response.

integer format: int32
detail

What went wrong with this particular request, when there is more to say than the title.

string
nullable
errors

For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).

object
key
additional properties
Array<string>
requestId
required

The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.

string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  },
  "requestId": "example"
}

428

Section titled “428”

This API key requires an Idempotency-Key header on every POST and PATCH.

Media typeapplication/problem+json

Why a request failed, in the RFC 9457 problem details format.

object
type
required

A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.

string
title
required

A short, fixed summary of the kind of problem.

string
status
required

The HTTP status code of the response.

integer format: int32
detail

What went wrong with this particular request, when there is more to say than the title.

string
nullable
errors

For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).

object
key
additional properties
Array<string>
requestId
required

The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.

string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  },
  "requestId": "example"
}

503

Section titled “503”

The service is temporarily unavailable. Retry after the Retry-After header.

Media typeapplication/problem+json

Why a request failed, in the RFC 9457 problem details format.

object
type
required

A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.

string
title
required

A short, fixed summary of the kind of problem.

string
status
required

The HTTP status code of the response.

integer format: int32
detail

What went wrong with this particular request, when there is more to say than the title.

string
nullable
errors

For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).

object
key
additional properties
Array<string>
requestId
required

The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.

string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  },
  "requestId": "example"
}