Skip to main content
POST
/
apps
/
{app_id}
/
auth
/
tokens
/
{token_id}
/
rotate
Rotate API key
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/auth/tokens/{token_id}/rotate \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>'
{
  "token_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "ip_allowlist": [
    "<string>"
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "formatted_token": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Use this API to rotate a Rich Authentication Token (App API Key) for a specific OneSignal app. Rotating a key revokes the current token and generates a new one under the same configuration—ideal when a token is lost or compromised but you don’t want to recreate and reconfigure it from scratch.
For background on different OneSignal API keys, see Keys & IDs.

​
How to use this API

Using your Organization API key (available in Organizations > Keys & IDs) you can rotate an app token associated with a given app. The token_id is a OneSignal-generated ID specific for 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-Type
string
default:application/json
required
​
Authorization
string
default:Key YOUR_ORGANIZATION_API_KEY
required

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

Path Parameters

​
app_id
string
default:YOUR_APP_ID
required

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

​
token_id
string
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.

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.

An API Key Token record (Rich Authentication Token). Different operations return different subsets of these fields:

  • GET tokens lists every field except formatted_token.
  • POST tokens (create) returns token_id and formatted_token.
  • POST tokens/{id}/rotate returns formatted_token only.
  • PATCH tokens/{id} updates the record; the response body is currently empty (consumers should re-fetch via GET).

formatted_token is the actual REST API Key and is shown ONCE — OneSignal does not store it. Keep it secret.

​
token_id
string<uuid>

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

​
name
string

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

​
ip_allowlist_mode
enum<string>

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

Available options:
disabled,
explicit
​
ip_allowlist
string[]

Allowed CIDR ranges. Only enforced when ip_allowlist_mode is explicit.

​
created_at
string<date-time>

ISO-8601 timestamp when the key was created.

​
updated_at
string<date-time>

ISO-8601 timestamp when the key was last updated.

​
formatted_token
string

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.