Skip to main content
POST
/
apps
/
{app_id}
/
auth
/
tokens
Create API key
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/auth/tokens \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "<string>",
  "ip_allowlist": [
    "<string>"
  ]
}
'
{
  "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 create a new App API Key (also called a Rich Authentication Token) for a specific OneSignal app. These keys are used to authenticate API requests at the app level and offer enhanced security features, including optional IP allowlisting.
For background on different OneSignal API keys, see Keys & IDs.

​
How to use this API

Use your Organization API Key, to authenticate. This key is different from the standard REST API key.

​
IP allowlisting

By default, the API key will not be restricted to any specific IP addresses. To enable IP allowlisting, you need to set the ip_allowlist_mode parameter to explicit and provide a list of allowed IP addresses in the ip_allowlist parameter. If you want to set the explicit range of IPs that can use this API key, add them by setting ip_allowlist_mode to explicit and in ip_allowlist add the IPs in CIDRs notation as an array of string values.

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.

Body

application/json
​
name
string
required

An internal name you set to help organize and track API keys (Rich Authentication Tokens). Maximum 128 characters.

​
ip_allowlist_mode
enum<string>

Defaults to disabled, can be set to explicit. If set to explicit, a list of network addresses in the form of CIDRs has to be specified in the ip_allowlist parameter.

Available options:
disabled,
explicit
​
ip_allowlist
string[]

An array of allowed networks in CIDRs notation. Only IPs in those ranges will be permitted to use the API key.

Response

The newly-created API key token. token_id and formatted_token are populated; formatted_token is the secret and is returned ONCE — store it now or rotate later.

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.