v1

latestOpenAPI 3.1.02026-07-26497885.9 KB

Rotate API key

Rotate an existing App API Key (Rich Authentication Token) for a OneSignal app. Useful when a token is compromised or needs replacement without creating a new key from scratch.

post/apps/{app_id}/auth/tokens/{token_id}/rotate

Path parameters

app_idstring required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

token_idstring required

The OneSignal-generated ID specific to the API key. This is not the API key itself. It is returned when creating an API key with Create API key. It can be found in the OneSignal dashboard and in the response body of the View API keys request.

Headers

Content-Typestring required

Authorizationstring required

Your Organization API key with prefix Key . See Keys & IDs.

Response

The rotated key's new secret. Only formatted_token is populated; everything else stays the same as before the rotate. Update your integration with the new secret immediately.

token_idstring uuid

OneSignal-generated identifier for this API key. NOT the API key itself — use this to manage the key in subsequent calls.

namestring

Internal name set when the key was created or last updated. Maximum 128 characters.

ip_allowlist_mode'disabled' | 'explicit'

When explicit, only requests from IP addresses matching ip_allowlist may use this key. Defaults to disabled.

ip_allowliststring[]

Allowed CIDR ranges. Only enforced when ip_allowlist_mode is explicit.

created_atstring date-time

ISO-8601 timestamp when the key was created.

updated_atstring date-time

ISO-8601 timestamp when the key was last updated.

formatted_tokenstring

The actual Rich Authentication Token (REST API Key). Returned in plaintext ONLY by the create and rotate endpoints, and ONLY immediately after that call. OneSignal does not store the secret — if you lose it, you must rotate the key. See Rotate API Key.