OneSignal's RESTful API is based on the REST Architecture and provides robust features that can be used for many operations.

Keys and Identifiers

REST API Key

Our API uses the Basic authentication scheme, which requires authentication for several endpoints. Locate or create your app's REST API Key by navigating to Dashboard > Settings > Keys & IDs. This key allows you to interact with the app that created the key. To interact with several apps, you must create separate API Keys. Refer to Keys & IDs to learn more.

Example

Set Authorization header to the API Key.

POST /notifications HTTP/1.1
Content-Type: application/json
Authorization: Basic MjAyYzJlOTAtMTY4Mi00ODFlLTg2MDYtZTM2YzllM2ZlZTVi
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"]
}

App ID

All requests require an App ID, which can be found using one of several methods:

• Inspecting the URL of the Dashboard page. For example, you login 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.