Partner

Rotate API token

Create a new partner api token with the role, display name and authentication type of an existing one, and shorten the old token's life to the overlap period (overlapSec, default 1 day, maximum 30 days) so clients can switch over. A certificate token needs a CSR for the new certificate. The same limits as submitApiTokenApplication apply to the new token.

POST/api/partner/rotateApiToken

Authorizations

x-auth-apikeystringheaderrequired

Your Rhombus API key. Must be accompanied by the x-auth-scheme header set to api-token (or partner-api-token for partner endpoints).

Authorizationstringheader

Instead of an API key, an OAuth access token: Bearer <token>, with the read, write, physical scopes.

OAuth explains tokens and scopes.

Headers

x-auth-schemeenum<string>headerdefault: partner-api-token

Authentication scheme identifier. Use api-token or partner-api-token with the x-auth-apikey header, api or partner-api with x-auth-apikey plus a client certificate, api-oauth-token or partner-api-oauth-token with x-auth-access-token, and federated-token with x-auth-ft. A request with Authorization: Bearer <token> and no x-auth-scheme is treated as OAuth, and federated-token may also be sent as the x-auth-scheme and x-auth-ft query parameters.

Available options: api-token, api, api-oauth-token, federated-token, partner-api-token, partner-api, partner-api-oauth-token

x-auth-orgstring<RUUID>header

Client organization UUID (22-character RUUID), for partner credentials only. With it the call runs in that client organization with the partner support authority's role. Without it a partner credential runs as the partner organization, which outside the partner endpoints is deprecated (responses carry Deprecation and Sunset: Tue, 05 Jan 2027 00:00:00 GMT). A malformed value returns 400 INVALID_AUTH_ORG; a client organization the partner cannot access returns 403 PARTNER_CLIENT_ACCESS_DENIED.

Length: 22 to 22

Body

application/json · object

Request object for rotating an API token: a new token with the old one's role, display name and authentication type, while the old one keeps working for an overlap period.

csrstring | nullbody

Certificate Signing Request for the new token's client certificate. Required when the token uses certificate authentication.

Example: "-----BEGIN CERTIFICATE REQUEST-----..."

expiresAtMsinteger<int64> | nullbody

When the new token expires, in epoch milliseconds. Optional for console, mobile and OAuth callers. Required when an API token makes the call: no later than that token's own expiry and at most 365 days from now.

overlapSecinteger<int32> | nullbody

How long the old token keeps working, in seconds. Defaults to 86400 (1 day), maximum 2592000 (30 days). The old token's expiry is only ever moved earlier.

Example: 86400

tokenUuidstring<RUUID> | nullbodyrequired

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

bash

curl --request POST \
  --url 'https://api2.rhombussystems.com/api/partner/rotateApiToken' \
  --header 'x-auth-scheme: partner-api-token' \
  --header 'x-auth-apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "csr": "-----BEGIN CERTIFICATE REQUEST-----...",
    "expiresAtMs": 0,
    "overlapSec": 86400,
    "tokenUuid": "AAAAAAAAAAAAAAAAAAAAAA"
  }'

import requests

url = "https://api2.rhombussystems.com/api/partner/rotateApiToken"
headers = {
    "x-auth-scheme": "partner-api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "csr": "-----BEGIN CERTIFICATE REQUEST-----...",
    "expiresAtMs": 0,
    "overlapSec": 86400,
    "tokenUuid": "AAAAAAAAAAAAAAAAAAAAAA"
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

const response = await fetch('https://api2.rhombussystems.com/api/partner/rotateApiToken', {
  method: 'POST',
  headers: {
    'x-auth-scheme': 'partner-api-token',
    'x-auth-apikey': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "csr": "-----BEGIN CERTIFICATE REQUEST-----...",
    "expiresAtMs": 0,
    "overlapSec": 86400,
    "tokenUuid": "AAAAAAAAAAAAAAAAAAAAAA"
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);

console.log(await response.json());

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "csr": "-----BEGIN CERTIFICATE REQUEST-----...",
              "expiresAtMs": 0,
              "overlapSec": 86400,
              "tokenUuid": "AAAAAAAAAAAAAAAAAAAAAA"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api2.rhombussystems.com/api/partner/rotateApiToken"))
            .header("x-auth-scheme", "partner-api-token")
            .header("x-auth-apikey", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

json

{
  "apiKey": "AAAAAAAAAAAAAAAAAAAAAA",
  "cert": "<string>",
  "certNotAfterMs": 0,
  "error": false,
  "errorCode": "<string>",
  "expiresAtMs": 0,
  "previousKeyExpiresAtMs": 0,
  "tokenUuid": "AAAAAAAAAAAAAAAAAAAAAA",
  "validCSR": true
}

Response

200 OK

application/json · object

Response object for rotating an API token: the new token, and when the old one stops working.

apiKeystring<RUUID> | null

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

certstring | null

certNotAfterMsinteger<int64> | null

When the client certificate expires, in epoch milliseconds (certificate tokens only)

errorboolean | null

errorCodestring | null

Stable, machine-readable code for the failure (one of the ApiErrorCode catalog) when error is true. Branch on this, not on errorMsg.

errorMsgstring | null

expiresAtMsinteger<int64> | null

When the new token expires, in epoch milliseconds. Absent when it does not expire.

previousKeyExpiresAtMsinteger<int64> | null

When the old token stops working, in epoch milliseconds

tokenUuidstring<RUUID> | null

base 64 (url-safe) uuid string

Example: "AAAAAAAAAAAAAAAAAAAAAA"

validCSRboolean | null

warningMsgstring | null

Errors

Like every operation, this one can also answer with the standard error body (errorCode, errorMsg). Errors explains each status and how to retry.

400 Bad Request. errorCode is one of: BAD_REQUEST, VALIDATION_FAILED, MISSING_REQUIRED_FIELD, INVALID_JSON, INVALID_REQUEST_BODY, FEATURE_NOT_ENABLED, INVALID_AUTH_ORG, LOCATION_NOT_FOUND.
401 Unauthorized. errorCode is one of: UNAUTHENTICATED, INVALID_CREDENTIAL, CREDENTIAL_EXPIRED, CREDENTIAL_REVOKED, CERTIFICATE_MISMATCH.
403 Forbidden. errorCode is one of: FORBIDDEN, DOMAIN_NOT_ALLOWED, DEVICE_SCOPE_MISMATCH, ROLE_NOT_PERMITTED, FUNCTIONALITY_REQUIRED, PARTNER_FUNCTIONALITY_REQUIRED, PERMISSION_REQUIRED, PARTNER_CLIENT_ACCESS_DENIED, HARDWARE_NOT_AVAILABLE, HARDWARE_ALREADY_REGISTERED, PARTNER_PORTAL_NOT_ENABLED, MANAGED_BY_MSP, SUPER_ADMIN_RESTRICTED_BY_MSP, MSP_DESIGNATION_INVALID, NOT_MANAGED_CLIENT.
429 Too Many Requests. errorCode is one of: RATE_LIMITED.
500 Internal Server Error. errorCode is one of: INTERNAL_ERROR.
503 Service Unavailable. errorCode is one of: SERVICE_UNAVAILABLE.