OneSignal Authentication: API Keys & Security (2026)

Authentication overview

OneSignal provides a suite of APIs and SDKs for managing user engagement through push notifications, in-app messaging, email, and SMS. Authentication for these services is primarily handled through API keys, which grant access to specific application resources and functionalities. Effective authentication mechanisms are critical for securing communication channels and preventing unauthorized access to user data and notification services. By requiring valid credentials, OneSignal ensures that only authorized applications and users can interact with its platform, safeguarding the integrity and privacy of your communication streams.

The authentication process typically involves providing an App ID and a REST API Key for server-to-server interactions, or managing user authentication for client-side operations. This system is designed to be straightforward for developers while maintaining a robust security posture, aligning with industry standards for API security, as outlined by organizations like the Internet Engineering Task Force (IETF).

Supported authentication methods

OneSignal's platform supports different authentication methods tailored to the specific context of interaction, whether it's direct API calls from a backend server or client-side operations through their SDKs. The primary methods revolve around API key management.

API Key Authentication

This is the most common method for server-side interactions with the OneSignal REST API. It involves using a unique App ID to identify your application and a REST API Key to authenticate requests. The REST API Key acts as a secret token, granting permission to perform actions like sending notifications, creating segments, or retrieving data programmatically.

User Authentication (External User ID)

For client-side operations or more personalized user experiences, OneSignal supports associating an External User ID with a OneSignal Player ID. While not a direct authentication method in the traditional sense, this allows for secure identification of users across different devices and platforms, enabling targeted messaging. When used with a JWT-authenticated user token, it provides a secure way to manage user-specific data and actions directly from the client.

Client-Side SDK Initialization

When integrating OneSignal SDKs into mobile or web applications, the primary authentication credential required is the App ID. This identifies your application to the OneSignal service, allowing the SDK to register devices and receive notifications. While the App ID is publicly available within your client application, sensitive operations typically require the REST API Key, which must be kept server-side.

Authentication methods summary

Getting your credentials

To interact with the OneSignal API or integrate their SDKs, you need to obtain specific credentials from your OneSignal dashboard. These credentials include the App ID and various API keys.

1. Create a OneSignal Account: If you don't already have one, sign up for a OneSignal account on their official website.
2. Create an Application: After logging in, you will need to create a new application (or select an existing one) within your dashboard. Each application represents a distinct project (e.g., a specific mobile app or website) and will have its own set of credentials.
3. Locate your App ID: The App ID is a unique identifier for your application. It can typically be found in the "Settings" > "Keys & IDs" section of your application within the OneSignal dashboard. This ID is used when initializing OneSignal SDKs in your client applications. For detailed instructions, refer to the OneSignal App ID documentation.
4. Retrieve your REST API Key: The REST API Key is a confidential key required for making server-to-server API calls. It's also located in the "Settings" > "Keys & IDs" section. This key grants full access to your application's data and notification sending capabilities, so it must be kept secure.
5. Generate a User Auth Key (Optional): If you plan to use User Authentication with JWTs, you will need to enable this feature and configure the necessary settings within your dashboard, which may involve generating additional keys or secrets for signing JWTs.

Always ensure that you are retrieving keys for the correct application when working with multiple projects.

Authenticated request example

When making API calls to OneSignal, the REST API Key is typically sent in the Authorization header of your HTTP request. The App ID is often included in the request URL or body, depending on the specific endpoint.

Here's an example of a curl command to send a push notification using the OneSignal REST API, demonstrating how to include the necessary authentication headers:

curl -X POST \ 
  https://onesignal.com/api/v1/notifications \ 
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: Basic YOUR_REST_API_KEY' \ 
  -d '{
    "app_id": "YOUR_APP_ID",
    "included_segments": ["Subscribed Users"],
    "contents": {"en": "Hello from OneSignal!"}
  }'

In this example:

• YOUR_REST_API_KEY should be replaced with your actual REST API Key from the OneSignal dashboard. The Basic prefix is part of the HTTP Basic Authentication scheme, even though OneSignal uses the key directly.
• YOUR_APP_ID should be replaced with your OneSignal App ID.

For programmatic examples in various languages, refer to the OneSignal API reference documentation.

Security best practices

Securing your OneSignal integration is paramount to protect user data and maintain the integrity of your communication channels. Adhering to these best practices can mitigate common security risks:

Treat REST API Keys as Secrets

• Never hardcode keys in client-side code: Your REST API Key should never be exposed in client-side code (e.g., JavaScript, mobile app bundles). It must reside on a secure backend server.
• Use environment variables: Store API keys in environment variables or a secure configuration management system on your server, rather than directly in your codebase.
• Restrict access: Limit access to API keys to only authorized personnel and systems.

Secure API Communication

• Always use HTTPS: All communication with the OneSignal API should occur over HTTPS to ensure data encryption in transit. OneSignal endpoints enforce HTTPS by default.
• Validate server certificates: Ensure your application validates SSL/TLS certificates to prevent man-in-the-middle attacks.

Implement Least Privilege

• Grant minimum necessary permissions: When OneSignal introduces role-based access control or different API key types, always assign the minimum permissions required for a given task.

Rotate Keys Periodically

• Regular key rotation: Periodically rotate your REST API Key to reduce the risk associated with a compromised key. If a key is compromised, generate a new one immediately and revoke the old one.

Client-Side SDK Security

• Obfuscate client-side code: While the App ID is public, obfuscating your client-side code can make it harder for attackers to reverse engineer and understand your application's interaction with OneSignal.
• Use User Authentication (JWT) for sensitive client-side operations: When associating external user IDs or performing other user-specific actions from the client, use the OneSignal User Authentication with JWTs to ensure data integrity and authenticity. This prevents malicious clients from impersonating users.

Monitor and Audit

• Monitor API usage: Keep an eye on your OneSignal API usage for any unusual patterns or spikes that might indicate unauthorized activity.
• Review access logs: Regularly review OneSignal's access logs (if available) to detect any suspicious login attempts or API calls.

By following these best practices, developers can significantly enhance the security posture of their OneSignal integrations, protecting both their applications and their users.