Rotate Workspace Key Secret

PATCH

{workspace}

ws_key

{workspace_key_id}

rotate

Rotate Workspace Key Secret

curl -X PATCH "https://management-api.suprsend.com/v1/{workspace}/ws_key/{workspace_key_id}/rotate/" \
  --header 'Authorization: ServiceToken <SERVICE_TOKEN>'

import requests

url = "https://management-api.suprsend.com/v1/{workspace}/ws_key/{workspace_key_id}/rotate/"

headers = {"ServiceToken <token>": "<api-key>"}

response = requests.patch(url, headers=headers)

print(response.text)

const options = {method: 'PATCH', headers: {'ServiceToken <token>': '<api-key>'}};

fetch('https://management-api.suprsend.com/v1/{workspace}/ws_key/{workspace_key_id}/rotate/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://management-api.suprsend.com/v1/{workspace}/ws_key/{workspace_key_id}/rotate/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_HTTPHEADER => [
    "ServiceToken <token>: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://management-api.suprsend.com/v1/{workspace}/ws_key/{workspace_key_id}/rotate/"

	req, _ := http.NewRequest("PATCH", url, nil)

	req.Header.Add("ServiceToken <token>", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://management-api.suprsend.com/v1/{workspace}/ws_key/{workspace_key_id}/rotate/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["ServiceToken <token>"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "ws_key_01ABCDEFGHJKMNPQRSTVWXYZ1",
  "name": "ops-cli",
  "key": "SS.WSK.YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
  "secret": "SS.WSS.ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ",
  "is_default": false,
  "is_active": true,
  "is_deleted": false,
  "allowed_domains": [],
  "created_at": "2026-09-28T11:12:23.557360Z",
  "created_by": {
    "name": "System User",
    "email": "org_XXXXXXXXXXXXXXXXXXXXXX@systemuser.suprsend.com"
  },
  "rotated_at": "2026-09-28T13:08:59.983999Z",
  "rotated_by": {
    "name": "System User",
    "email": "org_XXXXXXXXXXXXXXXXXXXXXX@systemuser.suprsend.com"
  },
  "deleted_at": null,
  "deleted_by": null
}

{
  "code": 401,
  "error_code": "authentication_failed",
  "type": "AuthenticationFailed",
  "message": "Invalid service token.",
  "detail": "Invalid service token."
}

{
  "code": 404,
  "error_code": "not_found",
  "type": "NotFound",
  "message": "workspace 'demo' not found",
  "detail": "workspace 'demo' not found"
}

Authorizations

ServiceToken <token>

string

header

required

You can get Service Token from SuprSend dashboard -> Account Settings -> Service Tokens section.

Path Parameters

workspace

string

required

Workspace slug (e.g. staging, production).

workspace_key_id

string

required

Workspace key identifier (e.g. ws_key_...).

Response

Rotation accepted. The response returns the updated record with a new secret; key is unchanged.

A workspace key/secret pair used to authenticate backend SDKs (Suprsend(workspace_key, workspace_secret)).

Unlike ws_api_key, both key and secret are returned in full plain text on every response - list, detail, create and rotate. Treat every response as sensitive: do not log it, do not surface it to browsers, and store the secret only in an environment variable or secrets manager.

string

Unique identifier of the workspace key. Format is ws_key_ followed by a 26-character ULID.

Example:

"ws_key_01ABCDEFGHJKMNPQRSTVWXYZ0"

name

string

Label for the workspace key. Unique across the workspace's ws_key records.

Example:

"ops-cli"

key

string

Full workspace key value. This is the workspace_key passed to backend SDKs when authenticating (Suprsend(workspace_key, workspace_secret)). Returned in plain text on every response.

Rotation does not change key - only secret is regenerated.

Example:

"SS.WSK.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

secret

string

Full workspace secret. This is the workspace_secret passed to backend SDKs when authenticating (Suprsend(workspace_key, workspace_secret)). Returned in plain text on every response, not masked and not "returned once".

Anyone with read access to this response can authenticate as this workspace. Handle every list, detail, create and rotate response as sensitive data.

Example:

"SS.WSS.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

is_default

boolean

Whether this is the workspace's default key/secret pair. The default record cannot be deleted; it can be rotated.

is_active

boolean

Whether this workspace key can authenticate requests.

is_deleted

boolean

Whether this workspace key has been deleted.

allowed_domains

string[]

Array of domain strings associated with the workspace key.

created_at

string<date-time>

Timestamp when the workspace key was created.

created_by

object | null

Identity that performed an action (created, updated, rolled, deleted, rotated).

Show child attributes

rotated_at

string<date-time> | null

Timestamp when the workspace secret was last rotated.

rotated_by

object | null

Identity that performed an action (created, updated, rolled, deleted, rotated).

Show child attributes

deleted_at

string<date-time> | null

Timestamp when the workspace key was deleted, if applicable.

deleted_by

object | null

Identity that performed an action (created, updated, rolled, deleted, rotated).

Show child attributes

⌘I

Rotate Workspace Key Secret

curl -X PATCH "https://management-api.suprsend.com/v1/{workspace}/ws_key/{workspace_key_id}/rotate/" \
  --header 'Authorization: ServiceToken <SERVICE_TOKEN>'

import requests

url = "https://management-api.suprsend.com/v1/{workspace}/ws_key/{workspace_key_id}/rotate/"

headers = {"ServiceToken <token>": "<api-key>"}

response = requests.patch(url, headers=headers)

print(response.text)

const options = {method: 'PATCH', headers: {'ServiceToken <token>': '<api-key>'}};

fetch('https://management-api.suprsend.com/v1/{workspace}/ws_key/{workspace_key_id}/rotate/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://management-api.suprsend.com/v1/{workspace}/ws_key/{workspace_key_id}/rotate/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_HTTPHEADER => [
    "ServiceToken <token>: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://management-api.suprsend.com/v1/{workspace}/ws_key/{workspace_key_id}/rotate/"

	req, _ := http.NewRequest("PATCH", url, nil)

	req.Header.Add("ServiceToken <token>", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://management-api.suprsend.com/v1/{workspace}/ws_key/{workspace_key_id}/rotate/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["ServiceToken <token>"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "ws_key_01ABCDEFGHJKMNPQRSTVWXYZ1",
  "name": "ops-cli",
  "key": "SS.WSK.YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
  "secret": "SS.WSS.ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ",
  "is_default": false,
  "is_active": true,
  "is_deleted": false,
  "allowed_domains": [],
  "created_at": "2026-09-28T11:12:23.557360Z",
  "created_by": {
    "name": "System User",
    "email": "org_XXXXXXXXXXXXXXXXXXXXXX@systemuser.suprsend.com"
  },
  "rotated_at": "2026-09-28T13:08:59.983999Z",
  "rotated_by": {
    "name": "System User",
    "email": "org_XXXXXXXXXXXXXXXXXXXXXX@systemuser.suprsend.com"
  },
  "deleted_at": null,
  "deleted_by": null
}

{
  "code": 401,
  "error_code": "authentication_failed",
  "type": "AuthenticationFailed",
  "message": "Invalid service token.",
  "detail": "Invalid service token."
}

{
  "code": 404,
  "error_code": "not_found",
  "type": "NotFound",
  "message": "workspace 'demo' not found",
  "detail": "workspace 'demo' not found"
}

API Reference

WORKSPACE & AUTH KEYS

WORKFLOWS

SCHEMAS

EVENTS

CATEGORIES

TRANSLATIONS

TEMPLATES

Authorizations

Path Parameters

Response