Skip to main content
This guide helps developers integrate OneSignal into mobile and web applications. Follow the sections in order for a first-time setup, or jump to the area you need.
  1. Get started — access your OneSignal App and find your API keys
  2. Set up messaging channels — install the SDK and configure channels
  3. SDK and API reference — detailed method, class, and endpoint documentation
  4. Users and identity — identify Users, manage Subscriptions, and secure access
  5. Testing and debugging — verify your integration before going live
  6. 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

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 call login 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.
Always test with test Subscriptions first. This lets you verify delivery, rendering, and deep links without affecting real Users.

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 the Authorization 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 via login. 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?

Call OneSignal.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 call login 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
We’re happy to help!