---
title: "Rotate API key"
method: POST
path: "/apps/{app_id}/auth/tokens/{token_id}/rotate"
---

# Rotate API key

`POST /apps/{app_id}/auth/tokens/{token_id}/rotate`

## Request

- Base URL: `https://api.onesignal.com`
- URL: `https://api.onesignal.com/apps/{app_id}/auth/tokens/{token_id}/rotate`
- Auth: none required

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.

## Path parameters

- `app_id` string, required
- `token_id` string, required

## Headers

- `Content-Type` string, required
- `Authorization` string, required

## Response `200`

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.

- ApiKeyToken: An API key token (Rich Authentication Token). Each operation returns a different subset of these fields: - **GET tokens** returns 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 and returns an empty body. Re-fetch with GET to see the change. `formatted_token` is the REST API key. OneSignal returns it only on create and rotate, and does not store it. Save it immediately.
  - `token_id` string, uuid: OneSignal-generated identifier for this API key. This is not the API key itself. Use `token_id` 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` 'disabled' | 'explicit': When `explicit`, only requests from IP addresses matching `ip_allowlist` may use this key. Defaults to `disabled`.
  - `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 REST API key (Rich Authentication Token). 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, rotate the key. See [Rotate API Key](/reference/rotate-api-key).

## Other responses

- `400`: 400
- `403`: Forbidden. Your organization permissions do not allow this action.
- `404`: Token not found in this app, or the App ID was wrong.
- `429`: Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.
- `503`: Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.

---

[API](https://skmtc.dev/onesignal/apis/api-onesignal-com.md) - [All operations](https://skmtc.dev/onesignal/apis/api-onesignal-com/llms.txt) - [OpenAPI document](https://skmtc.dev/onesignal/apis/api-onesignal-com/revisions/36dfd39b1be3?raw)