- Get started — access your OneSignal App and find your API keys
- Set up messaging channels — install the SDK and configure channels
- SDK and API reference — detailed method, class, and endpoint documentation
- Users and identity — identify Users, manage Subscriptions, and secure access
- Testing and debugging — verify your integration before going live
- Webhooks and events — receive message events server-side
Get started
If your team already has a OneSignal account, ask an admin to invite you to the Organization. Otherwise, create an account to get started. Your OneSignal App is where User and message data lives. Each App has its own App ID, API keys, and messaging channels. You can have multiple Apps in a single Organization for different projects or environments.Apps, Organizations, and accounts
How Apps, Organizations, and accounts relate to each other.
Keys and IDs
Find your App ID, REST API key, and Organization ID for authentication.
Add team members
Invite developers and assign roles within your Organization.
Usage and billing
Billing, invoices, and usage details.
Set up messaging channels
Install the OneSignal SDK to create and track user engagement for your platforms. Each message channel has its own setup guide covering credentials, SDK initialization, and tutorials.Mobile SDK setup
SDK setup for iOS, Android, Huawei, and Amazon. Enables push notifications, in-app messages, and Live Activities.
Web push
Web SDK installation and browser push notification setup.
Email channel configuration and sender domain verification.
In-app messages
Display rich, interactive messages within your mobile app.
SMS
SMS channel setup and carrier registration.
RCS
Rich messaging with branded content and read receipts.
Live Activities
Dynamic iOS lock screen updates. Similar capabilities available for Android.
Mobile push prompts
Configure opt-in prompts to collect push Subscriptions on mobile.
Web push prompts
Configure opt-in prompts to collect push Subscriptions on web.
SDK and API reference
Detailed documentation for client SDKs, server SDKs, and the REST API.Mobile SDK reference
Methods, classes, and event hooks for iOS, Android, and cross-platform SDKs.
Web SDK reference
Initialization, User management, Subscription methods, and custom triggers.
Server SDK reference
Install and configure server SDKs for Node.js, Python, Java, Go, PHP, Ruby, C#, and Rust.
REST API overview
Endpoints, authentication, rate limits, and request/response formats.
Transactional messages
Send OTPs, receipts, and time-sensitive alerts via API with personalized data.
Server SDKs on GitHub
Source code and examples for all server SDK libraries.
Users and identity
OneSignal assigns each person a OneSignal ID and tracks their devices, email addresses, and phone numbers as Subscriptions. Users are anonymous until you calllogin with an External ID to identify them. Identifying Users unifies their Subscriptions across channels and devices.
Users
User model, External ID, anonymous vs. identified Users, and login/logout.
Subscriptions
Devices, email addresses, and phone numbers that receive your messages.
Identity verification
Require server-generated JWTs to prevent User impersonation.
Aliases
Map custom identifiers to Users for cross-platform tracking and integrations.
Tags
Set key-value data on Users for personalization and segmentation.
Custom events
Track User actions to trigger Journeys or power analytics.
Testing and debugging
Verify your integration works before sending to your full audience.Test Subscriptions
Find and configure test Subscriptions for push, email, and SMS.
Debug logs
Capture verbose SDK logs from mobile apps for troubleshooting.
Mobile troubleshooting
Resolve common push delivery, APNS, and in-app messaging issues.
Web troubleshooting
Fix service worker, browser compatibility, and web push issues.
Webhooks and events
Receive message events server-side for analytics, automation, or syncing with external systems.Event Streams
Stream clicks, opens, receives, and other message events to your data warehouse in real time.
Journey webhooks
Send HTTP requests to your server from Journey steps.
Web push webhooks
HTTP callbacks for web push display, click, and dismiss events.
FAQ
How do I authenticate REST API requests?
Include your REST API key in theAuthorization header as a bearer token: Authorization: Key YOUR_REST_API_KEY. Find your key in Settings > Keys and IDs in the OneSignal dashboard. See Keys and IDs for details.
What is the difference between client SDKs and server SDKs?
Client SDKs (mobile and web) run in your app on the User’s device. They handle Subscription registration, permission prompts, in-app messages, and User identification vialogin. Server SDKs run on your backend and call the REST API to send messages, manage Users, and export data.
How do I identify Users across devices?
CallOneSignal.login("your_external_id") on each device after the User signs in. OneSignal merges all Subscriptions with the same External ID under a single User. See Users for implementation details.
Do I need to set up identity verification?
Identity verification is optional but strongly recommended for production apps. Without it, any client can calllogin with an arbitrary External ID. Enabling identity verification requires updating the OneSignal SDK to use a server-generated JWT, preventing impersonation.
Need help?Chat with our Support team or email
support@onesignal.comPlease include:- Details of the issue you’re experiencing and steps to reproduce if available
- Your OneSignal App ID
- The External ID or Subscription ID if applicable
- The URL to the message you tested in the OneSignal Dashboard if applicable
- Any relevant logs or error messages