Keys and Identifiers

REST API Key

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.

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 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 a bad actor has time 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.

Authentication

Our API uses the Basic authentication scheme when authentication is required.

To use the REST API Key , set the Authorization header to Basic followed by the key.

API Key: MjAyYzJlOTAtMTY4Mi00ODFlLTg2MDYtZTM2YzllM2ZlZTVi
Header: Authorization: Basic MjAyYzJlOTAtMTY4Mi00ODFlLTg2MDYtZTM2YzllM2ZlZTVi

Example

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"]
}

Generating and Managing API Keys

Navigate to Dashboard: Go to Dashboard > Settings > Keys & IDs.
Create a New Key: Click on Create New Key to generate a new API Key for your app.
Manage Keys: Use the Keys & IDs section to regenerate your REST API Key

Error Handling

When making requests, ensure that your API Key or Bearer token is valid and correctly formatted. Invalid or expired keys will result in authentication errors. The API will return the following error messages for common issues:

Invalid API Key: 401 Unauthorized
Missing Authorization Header: 400 Bad Request