Server SDK reference

All OneSignal server SDKs are generated from the same OpenAPI specification, so they share a consistent interface regardless of language. Each SDK wraps the OneSignal REST API and provides typed models for requests and responses. Every SDK covers the same set of endpoints: Notifications, Users, Subscriptions, Segments, Templates, Live Activities, Custom Events, API Keys, and Apps.

Available SDKs

Language	Package	Repository
Node.js	@onesignal/node-onesignal	GitHub
Python	onesignal-python-api	GitHub
Java	onesignal-java-client	GitHub
Go	onesignal-go-api	GitHub
PHP	onesignal/onesignal-php-api	GitHub
Ruby	onesignal	GitHub
C# (.NET)	OneSignalApi	GitHub
Rust	onesignal-rust-api	GitHub

Before you begin

Gather these values from your OneSignal dashboard before installing an SDK. See Keys & IDs for where to find each one.

App ID — the unique identifier for your OneSignal app.
REST API Key — required for most endpoints (sending notifications, managing users).
Organization API Key (optional) — only required for organization-level endpoints like creating or listing apps.

Installation

Version numbers below are examples. Check the package registry for each SDK to install the latest version.

npm install @onesignal/node-onesignal

Requires Python 3.6+.

pip install onesignal-python-api

Requires Java 1.8+ and Maven 3.8.3+ or Gradle 7.2+.Maven

<dependency>
  <groupId>com.onesignal</groupId>
  <artifactId>onesignal-java-client</artifactId>
  <version>5.8.1</version>
</dependency>

Gradle

implementation "com.onesignal:onesignal-java-client:5.8.1"

go get github.com/OneSignal/onesignal-go-api/v5

Requires PHP 7.3+.Add to composer.json:

{
  "require": {
    "onesignal/onesignal-php-api": "^5.3"
  }
}

Then run composer update.

Add to your Gemfile:

gem 'onesignal', '~> 5.8.0'

Then run bundle install.

dotnet add package OneSignalApi

Add to Cargo.toml under [dependencies]:

onesignal-rust-api = "5.8.0"

Configuration

Every SDK requires authentication via API keys. Two key types are available:

REST API Key — required for most endpoints (sending notifications, managing users, etc.). Found in your app’s Settings > Keys & IDs.
Organization API Key — only required for organization-level endpoints like creating or listing apps. Found in Organization Settings.

Store your API keys in environment variables or a secrets manager. Never commit them to source control. The examples below read from ONESIGNAL_REST_API_KEY and ONESIGNAL_ORGANIZATION_API_KEY.

const OneSignal = require('@onesignal/node-onesignal');

const configuration = OneSignal.createConfiguration({
  restApiKey: process.env.ONESIGNAL_REST_API_KEY,
  organizationApiKey: process.env.ONESIGNAL_ORGANIZATION_API_KEY,
});

const client = new OneSignal.DefaultApi(configuration);

import os
import onesignal
from onesignal.api import default_api

configuration = onesignal.Configuration(
    rest_api_key=os.environ['ONESIGNAL_REST_API_KEY'],
    organization_api_key=os.environ.get('ONESIGNAL_ORGANIZATION_API_KEY'),
)

with onesignal.ApiClient(configuration) as api_client:
    client = default_api.DefaultApi(api_client)
    # Call client.create_notification(...) and other methods here.

Because ApiClient is a context manager, make your client.create_notification(...) calls inside the with block so the underlying HTTP session stays open.

import com.onesignal.client.ApiClient;
import com.onesignal.client.Configuration;
import com.onesignal.client.auth.HttpBearerAuth;
import com.onesignal.client.api.DefaultApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

HttpBearerAuth restApiAuth = (HttpBearerAuth) defaultClient
    .getAuthentication("rest_api_key");
restApiAuth.setBearerToken(System.getenv("ONESIGNAL_REST_API_KEY"));

HttpBearerAuth orgApiAuth = (HttpBearerAuth) defaultClient
    .getAuthentication("organization_api_key");
orgApiAuth.setBearerToken(System.getenv("ONESIGNAL_ORGANIZATION_API_KEY"));

DefaultApi client = new DefaultApi(defaultClient);

import (
    "context"
    "os"

    onesignal "github.com/OneSignal/onesignal-go-api/v5"
)

restAuth := context.WithValue(
    context.Background(),
    onesignal.RestApiKey,
    os.Getenv("ONESIGNAL_REST_API_KEY"),
)

orgAuth := context.WithValue(
    restAuth,
    onesignal.OrganizationApiKey,
    os.Getenv("ONESIGNAL_ORGANIZATION_API_KEY"),
)

apiClient := onesignal.NewAPIClient(onesignal.NewConfiguration())

use onesignal\client\api\DefaultApi;
use onesignal\client\Configuration;
use GuzzleHttp;

$config = Configuration::getDefaultConfiguration()
    ->setRestApiKeyToken(getenv('ONESIGNAL_REST_API_KEY'))
    ->setOrganizationApiKeyToken(getenv('ONESIGNAL_ORGANIZATION_API_KEY'));

$client = new DefaultApi(
    new GuzzleHttp\Client(),
    $config
);

require 'onesignal'

OneSignal.configure do |config|
  config.rest_api_key = ENV['ONESIGNAL_REST_API_KEY']
  config.organization_api_key = ENV['ONESIGNAL_ORGANIZATION_API_KEY']
end

client = OneSignal::DefaultApi.new

using OneSignalApi.Api;
using OneSignalApi.Client;

var config = new Configuration();
config.BasePath = "https://api.onesignal.com";
config.AccessToken = Environment.GetEnvironmentVariable("ONESIGNAL_REST_API_KEY");

var client = new DefaultApi(config);

The .NET SDK’s Configuration.AccessToken holds a single bearer token. To call organization-level endpoints, initialize a separate Configuration with your Organization API Key. See the .NET DefaultApi docs for per-endpoint auth requirements.

use onesignal::apis::configuration::Configuration;
use std::env;

fn create_configuration() -> Configuration {
    let mut config = Configuration::new();
    config.rest_api_key_token = env::var("ONESIGNAL_REST_API_KEY").ok();
    config.organization_api_key_token = env::var("ONESIGNAL_ORGANIZATION_API_KEY").ok();
    config
}

Send a push notification

Send push notifications to web and mobile Subscriptions by targeting a segment. Each example wraps the send call in try/catch (or the language equivalent) so failures surface instead of silently swallowing errors.

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Hello from OneSignal!' };
notification.headings = { en: 'Push Notification' };
notification.included_segments = ['Subscribed Users'];

try {
  const response = await client.createNotification(notification);
  console.log('Notification ID:', response.id);
} catch (error) {
  console.error('Failed to create notification:', error);
}

.NET: Normalize newline characters manually

The .NET SDK does not normalize newline characters automatically. If your content contains \r\n, normalize it before passing to Contents:

var normalizedContent = yourContent
    .Replace("\\r\\n", "\n")
    .Replace("\\n", "\n")
    .Replace("\r\n", "\n")
    .Replace("\r", "\n");

Send an email

Send emails to Subscriptions with the email channel.

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.email_subject = 'Important Update';
notification.email_body = '<h1>Hello!</h1><p>This is an HTML email.</p>';
notification.included_segments = ['Subscribed Users'];
notification.channel_for_external_user_ids = 'email';

try {
  const response = await client.createNotification(notification);
  console.log('Notification ID:', response.id);
} catch (error) {
  console.error('Failed to create notification:', error);
}

Send an SMS

Send SMS text messages to Subscriptions with the sms channel.

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Your SMS message content here' };
notification.included_segments = ['Subscribed Users'];
notification.channel_for_external_user_ids = 'sms';
notification.sms_from = '+15551234567';

try {
  const response = await client.createNotification(notification);
  console.log('Notification ID:', response.id);
} catch (error) {
  console.error('Failed to create notification:', error);
}

Common send patterns

Target specific users, target specific devices, or schedule delivery. The JSON field names shown below map identically across every SDK — call the equivalent setter on your Notification object (setIncludeAliases / include_aliases, setSendAfter / send_after, etc.).

Send by external ID

Send to specific users by their external_id alias. You must set target_channel when using aliases so OneSignal knows which channel to route the message on.

Keys under include_aliases must match API alias labels exactly (for example, external_id, not externalId).

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Hello from OneSignal!' };
notification.include_aliases = { external_id: ['YOUR_USER_EXTERNAL_ID'] };
notification.target_channel = 'push';

const response = await client.createNotification(notification);

Send by subscription ID

Send to specific subscriptions by their OneSignal-generated subscription ID. Use this when you already know the exact devices or channels you want to reach.

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Hello from OneSignal!' };
notification.include_subscription_ids = ['SUBSCRIPTION_ID_1', 'SUBSCRIPTION_ID_2'];

const response = await client.createNotification(notification);

Schedule a send

Set send_after to a future timestamp to schedule delivery. Optionally set delayed_option to timezone or last-active to deliver per-subscription at a local time.

const notification = new OneSignal.Notification();
notification.app_id = 'YOUR_APP_ID';
notification.contents = { en: 'Reminder: your event starts soon.' };
notification.included_segments = ['Subscribed Users'];
notification.send_after = 'Thu Sep 24 2026 14:00:00 GMT-0700';

const response = await client.createNotification(notification);

Verify your setup

After calling createNotification, check the response for a non-empty id to confirm the notification was accepted:

Successful response

{
  "id": "b6b326a8-40aa-4204-b430-73cbc0f5d5b6",
  "recipients": 42,
  "external_id": null
}

The API may return HTTP 200 with an empty id when no matching subscribed recipients are found. Always check response.id before assuming the send succeeded, and inspect response.errors for details.

Response with no matching recipients

{
  "id": "",
  "recipients": 0,
  "errors": ["All included players are not subscribed"]
}

If you see an empty id, common causes are:

Segment name is misspelled or has the wrong case (segment names are case-sensitive).
The external_id or subscription ID does not exist in your app.
All targeted subscriptions are unsubscribed.

Common errors

Status	Meaning	Action
400	Malformed request or invalid field	Check field names and payload shape against the REST API reference.
401	Missing or invalid API key	Verify the key value and that it matches the app you’re targeting.
403	Wrong key scope (e.g. app REST key for an org endpoint)	Use the Organization API Key for org-level endpoints.
404	App, notification, user, or subscription not found	Verify the ID or alias in the dashboard.
409	Conflict — duplicate resource	For idempotent sends, this typically means the `idempotency_key` was replayed.
429	Rate limit exceeded	Wait for the `Retry-After` header before retrying; use exponential backoff.
5xx	Server error	Retry with exponential backoff.

Full API reference

Each server SDK supports the same set of endpoints — Notifications, Users, Subscriptions, Segments, Templates, Live Activities, Custom Events, API Keys, and Apps. The DefaultApi docs list every method; the models docs describe request and response shapes. Each SDK also ships an AGENTS.md with an integration guide tailored to LLM-assisted coding.

SDK	API methods	Models	LLM/agent guide
Node.js	DefaultApi.md	models/	AGENTS.md
Python	DefaultApi.md	docs/	AGENTS.md
Java	DefaultApi.md	docs/	AGENTS.md
Go	DefaultApi.md	docs/	AGENTS.md
PHP	DefaultApi.md	docs/Model/	AGENTS.md
Ruby	DefaultApi.md	docs/	AGENTS.md
C# (.NET)	DefaultApi.md	docs/	AGENTS.md
Rust	default_api docs	docs/	AGENTS.md

For the underlying REST API, see the complete API reference.

FAQ

Which server SDK should I choose?

Use the SDK that matches your backend language. All server SDKs are generated from the same OpenAPI specification and support the same endpoints, so functionality is identical across languages.

What is the difference between the REST API Key and Organization API Key?

The REST API Key is scoped to a single app and is required for most operations like sending notifications and managing users. The Organization API Key is scoped to your organization and is only needed for creating or listing apps. Most integrations only need the REST API Key.

Can I use the REST API directly instead of an SDK?

Yes. The server SDKs are convenience wrappers around the OneSignal REST API. You can call the API directly using any HTTP client with the key authentication scheme (Authorization: key YOUR_REST_API_KEY).

Are these SDKs auto-generated?

Yes. All server SDKs are generated from the OneSignal OpenAPI specification using OpenAPI Generator. This ensures consistent API coverage across all languages.

REST API overview

Endpoints, authentication, rate limits, and request/response formats.

Keys & IDs

Find your App ID, REST API key, and Organization API key.

Transactional messages

Send OTPs, receipts, and time-sensitive alerts via API with personalized data.

Identity verification

Secure your integration with server-generated JWTs to prevent User impersonation.

​Available SDKs

​Before you begin

​Installation

​Configuration

​Send a push notification

​Send an email

​Send an SMS

​Common send patterns

​Verify your setup

​Common errors

​Full API reference

​FAQ

​Which server SDK should I choose?

​What is the difference between the REST API Key and Organization API Key?

​Can I use the REST API directly instead of an SDK?

​Are these SDKs auto-generated?

​Related pages

REST API overview

Keys & IDs

Transactional messages

Identity verification

Available SDKs

Before you begin

Installation

Configuration

Send a push notification

Send an email

Send an SMS

Common send patterns

Verify your setup

Common errors

Full API reference

FAQ

Which server SDK should I choose?

What is the difference between the REST API Key and Organization API Key?

Can I use the REST API directly instead of an SDK?

Are these SDKs auto-generated?

Related pages