Server REST API Reference
Log InSign Up

Quick start API guide

Basic setup instructions for OneSignal's REST API.

Keys and identifiers

App ID

All requests require an App ID, which can be found using one of the following ways:

  • Inspecting the URL of the Dashboard page. For example, you log in to onesignal.com and click your app to get https://dashboard.onesignal.com/apps/202d4f61-1ca9-42df-9d36-bb17d8123abc.
    • The App ID is 202d4f61-1ca9-42df-9d36-bb17d8123abc.
  • Settings page in the Dashboard. See Keys & IDs.
  • Inspecting a successful response from a Configuration API.

See Notification Parameters to learn more about this identifier and other notification-specific parameters.

Key Safety

It's critical to keep your API keys secure. Your App ID is public but REST API Keys enable you to control almost every aspect of your app, including managing subscriptions, modifying user data, and sending messages to your users. Good security hygiene can lower the risks of bad actors accessing your apps.

  • Don't store keys in source code.
  • Don't push keys to GitHub.
  • Don't leak keys in your app.
  • Don't email keys.
  • Don't share keys in chat apps (e.g., Slack, Discord, Zoom, Meet, Teams, SMS, etc).
  • Don't store keys in a database, especially when unencrypted.
  • Do store keys in your local environment or a password or key manager.

Responding to Incidents

If you suspect your app may have been compromised, generate a new REST API Key as soon as possible. Doing so will limit the time a bad actor has to carry out malicious activity. To generate a new key, navigate to Dashboard > Settings > Keys & IDs, then click the Generate New API Key button. See Account Security for details.

API key

Your app's API key authenticates your requests to send messages, manage users, and more. Locate or create your app API key by navigating to Dashboard > Settings > Keys & IDs. Refer to Keys & IDs to learn more.

Authentication

To authenticate your requests, set the Authorization header to the API Key preceded by the word key.

Example

  • Given the API Key: os_v2_app_z4akfa25dza3hndyu4catxzjk2nadsy6nsgummfvtcvqeyhy4mjs7wcqjep6xuvvxx22k4r633d42vuzmzb3pbw5l7t4lom7fqakwki
  • The auth header becomes: Authorization: Key os_v2_app_z4akfa25dza3hndyu4catxzjk2nadsy6nsgummfvtcvqeyhy4mjs7wcqjep6xuvvxx22k4r633d42vuzmzb3pbw5l7t4lom7fqakwki
POST /notifications HTTP/1.1
Content-Type: application/json
Authorization: Key os_v2_app_z4akfa25dza3hndyu4catxzjk2nadsy6nsgummfvtcvqeyhy4mjs7wcqjep6xuvvxx22k4r633d42vuzmzb3pbw5l7t4lom7fqakwki
Host: api.onesignal.com
Connection: close
Content-Length: 220

{
  "app_id":"202d4f61-1ca9-42df-9d36-bb17d8123abc",
  "contents":{"en":"Hello, World","es":"Hola Mundo","fr":"Bonjour le monde","zh-Hans":"\u4f60\u597d\u4e16\u754c"},
  "target_channel":"push",
  "included_segments":["All Subscribers"]
}