> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create an app
> Programmatically create a new OneSignal app via the REST API. This guide explains required fields, supported platform configurations (Web, Android, iOS), and how to properly authenticate using your Organization API key.
## Overview
Use this API to programmatically create a new OneSignal app. This is useful for automating app setup, particularly when managing multiple apps or organizations, and avoids needing to manually use the OneSignal Dashboard.
You can create an app under an existing organization or generate a new one. Push platform configurations for Web, Android, and iOS can be defined during app creation, though **Email** and **SMS** must be set up manually via the [OneSignal Dashboard](/docs/en/channel-setup).
For an overview of how apps and organizations work in OneSignal, see [Apps & Organizations](/docs/en/apps-organizations).
***
## How to use this API
Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key.
The Organization API key must be assocated with the `organization_id` in the request body.
### Web push configuration
The following parameters are **required** for web push setup:
* `site_name`
* `chrome_web_origin`
* `safari_site_origin`
* `safari_apns_p12`: Empty string OR your Base64 encoded p12 certificate for Safari Push Notifications.
* `safari_apns_p12_password`: Empty string OR Password for your `safari_apns_p12` file if set.
URLs must use `https://` and match your site’s [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin).
`safari_apns_p12` and `safari_apns_p12_password` are required for `safari_site_origin` to be set. If you do not have your own Safari p12 certificate, they should be included with blank values.
If you use your own p12 certificate, you must update it every year.
If you need help Base64 encoding your p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
**Recommended parameters**:
* `chrome_web_default_notification_icon`: URL of a `256x256px` PNG for Chrome.
* `safari_icon_256_256`: URL of a `256x256px` PNG for Safari.
***
### Android mobile push configuration
The following parameter is **required** for Android push notifications. See [Android: Firebase Credentials](/docs/en/android-firebase-credentials).
* `fcm_v1_service_account_json`
If you need help Base64 encoding your FCM Service Account JSON file, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
***
### iOS mobile push configuration
iOS mobile push can be configured using either a p8 or a p12 authentication.
If you need to Base64 encode your p8 key or p12 certificate, you can use the following site: [https://www.base64encode.org](https://www.base64encode.org)
The following parameters are **required** if using [p8 Token-based connection to APNS](/docs/en/ios-p8-token-based-connection-to-apns):
* `apns_key_id`
* `apns_team_id`
* `apns_bundle_id`
* `apns_p8`
The following parameters are **required** if using [p12 APNS Authentication](/docs/en/ios-p12-generate-certificates):
* `apns_p12`
* `apns_p12_password`
**Optional parameters** :
* `additional_data_as_root_payload`: If set to `true`, the `data` paramater in your push notification payload will be added to the root payload of the notification. Helpful for customizations that require access to the data outside of our [OSNotification payload `additionalData` property](/docs/en/osnotification-payload).
***
## OpenAPI
````yaml POST /apps
openapi: 3.1.0
info:
title: api.onesignal.com
version: '11.6'
servers:
- url: https://api.onesignal.com
security:
- {}
paths:
/apps:
post:
summary: Create an app
description: >-
Programmatically create a new OneSignal app via the REST API. This guide
explains required fields, supported platform configurations (Web,
Android, iOS), and how to properly authenticate using your Organization
API key.
operationId: create-an-app
parameters:
- name: Content-Type
in: header
required: true
schema:
type: string
default: application/json
- name: Authorization
in: header
description: >-
Your Organization API key with prefix `Key `. See [Keys &
IDs](/docs/en/keys-and-ids).
required: true
schema:
type: string
default: Key YOUR_ORGANIZATION_API_KEY
requestBody:
content:
application/json:
schema:
type: object
required:
- name
- organization_id
properties:
name:
type: string
description: >-
An internal name you set to help organize and track Apps.
Maximum 128 characters.
default: NAME_OF_NEW_APP
organization_id:
type: string
description: >-
The [Organization ID](/docs/en/keys-and-ids#organization-id)
that the app will be associated with.
default: YOUR_ORG_ID
chrome_web_origin:
type: string
description: >-
The HTTPS
[origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin)
URL for your website. Required for web push notifications.
site_name:
type: string
description: >-
The name of your website. Used for web push notification
titles when omitted from the notification payload. Required
for web push notifications.
default: SITE_NAME
safari_site_origin:
type: string
description: >-
The HTTPS
[origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin)
URL for your website. Required for web push notifications
for Safari and should be the same as `chrome_web_origin`.
chrome_web_default_notification_icon:
type: string
description: >-
The full `https` URL to your default icon resource. The icon
should be a `256x256px` PNG.
safari_icon_256_256:
type: string
description: >-
The full `https` URL to your default icon resource. The icon
should be a `256x256px` PNG.
safari_apns_p12:
type: string
description: >-
A Base64 encoded p12 certificate for Safari Push
Notifications. If omitted, we will assign one to your app
for you.
safari_apns_p12_password:
type: string
description: The password for the `safari_apns_p12` file if applicable.
fcm_v1_service_account_json:
type: string
description: >-
Your FCM Service Account JSON file converted to base64
format. See [Android: Firebase
Credentials](/docs/android-firebase-credentials). Required
for Android mobile push notifications.
apns_p8:
type: string
description: >-
A Base64 encoded p8 file for iOS mobile Push Notifications.
Omit if using `apns_p12`. See [p8 Token-based connection to
APNS](/docs/ios-p8-token-based-connection-to-apns).
apns_env:
type: string
description: >-
The [APS Environment
Entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/aps-environment)
to specify whether this is a `production` or `development`
environment. Defaults to `production`. Use with `apns_p8`.
Enum:
- production
- development
apns_key_id:
type: string
description: >-
The APNS Key ID. Use with `apns_p8`. See [p8 Token-based
connection to
APNS](/docs/ios-p8-token-based-connection-to-apns).
apns_team_id:
type: string
description: >-
The APNS Team ID. Use with `apns_p8`. See [p8 Token-based
connection to
APNS](/docs/ios-p8-token-based-connection-to-apns).
apns_bundle_id:
type: string
description: >-
The Bundle ID for your app. Use with `apns_p8`. See [p8
Token-based connection to
APNS](/docs/ios-p8-token-based-connection-to-apns).
apns_p12:
type: string
description: >-
A Base64 encoded p12 certificate for iOS mobile push
notifications. Omit if using `apns_p8`. See [p12 APNS
Authentication](/docs/ios-p12-generate-certificates).
apns_p12_password:
type: string
description: The password for the `apns_p12` file if applicable.
additional_data_is_root_payload:
type: boolean
description: >-
If set to `true`, the `data` paramater in your push
notification payload will be added to the root payload of
the notification. Helpful for customizations that require
access to the data outside of our [OSNotification payload
`additionalData` property](/docs/osnotification-payload).
default: false
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
id:
description: The OneSignal App ID in UUID v4 format.
type: string
name:
description: >-
An internal name you set to help organize and track Apps.
Maximum 128 characters.
type: string
players:
description: The total number of Subscriptions in the app.
type: integer
messageable_players:
description: >-
The number of Subscriptions eligible to receive messages
in the app.
type: integer
created_at:
description: The date and time the app was created.
type: string
updated_at:
description: The date and time the app was last updated.
type: string
organization_id:
description: The Organization ID in which the app was created.
type: string
'403':
description: >-
Forbidden. The Authorization key does not have permission to create
an app under this organization, or the request violates the
organization's policy.
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorResponse'
example:
errors:
- >-
You do not have permission to create an app in this
organization.
'404':
description: >-
Either the referenced organization or the source app (when copying
configuration) was not found, or your API key cannot reach it.
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorResponse'
example:
errors:
- Organization not found
'429':
description: >-
Rate limit exceeded. Wait the number of seconds in the `Retry-After`
header before retrying.
headers:
Retry-After:
description: >-
Number of seconds to wait before retrying the request. Always
emitted on 429 responses.
schema:
type: integer
minimum: 0
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorResponse'
example:
errors:
- API rate limit exceeded
'503':
description: >-
Service temporarily unavailable. Retry after a short backoff. The
body may be empty or non-JSON in some failure modes.
headers:
Retry-After:
description: >-
Number of seconds to wait before retrying. Optional — may be
absent when the response is generated upstream.
schema:
type: integer
minimum: 0
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorResponse'
example:
errors:
- Service temporarily unavailable
deprecated: false
x-codeSamples:
- lang: typescript
label: Node.js SDK
source: |-
import Onesignal from '@onesignal/node-onesignal';
const configuration = Onesignal.createConfiguration({
organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',
});
const apiInstance = new Onesignal.DefaultApi(configuration);
// App
const app: Onesignal.App = {
name: "name_example",
android_gcm_sender_id: "android_gcm_sender_id_example",
gcm_key: "gcm_key_example",
chrome_web_origin: "chrome_web_origin_example",
chrome_key: "chrome_key_example",
chrome_web_default_notification_icon: "chrome_web_default_notification_icon_example",
chrome_web_sub_domain: "chrome_web_sub_domain_example",
apns_env: "sandbox",
apns_p12: "apns_p12_example",
apns_p12_password: "apns_p12_password_example",
safari_apns_p12: "safari_apns_p12_example",
safari_apns_p12_password: "safari_apns_p12_password_example",
apns_key_id: "apns_key_id_example",
apns_team_id: "apns_team_id_example",
apns_bundle_id: "apns_bundle_id_example",
apns_p8: "apns_p8_example",
safari_site_origin: "safari_site_origin_example",
safari_icon_256_256: "safari_icon_256_256_example",
site_name: "site_name_example",
organization_id: "organization_id_example",
additional_data_is_root_payload: true,
};
try {
const response = await apiInstance.createApp(app);
console.log(response);
} catch (e) {
if (e instanceof Onesignal.ApiException) {
// `e.errorMessages` flattens any error-envelope shape to a `string[]`;
// the raw parsed body remains on `e.body`.
console.error("createApp failed: HTTP " + e.code, e.errorMessages);
} else {
throw e;
}
}
- lang: python
label: Python SDK
source: >-
import onesignal
from onesignal.api import default_api
from onesignal.models import *
from pprint import pprint
# See configuration.py for a list of all supported configuration
parameters.
# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token
for authorization, while others require REST_API_KEY.
# We recommend adding both of them in the configuration page so that
you will not need to figure it out yourself.
configuration = onesignal.Configuration(
rest_api_key = "YOUR_REST_API_KEY", # App REST API key required for most endpoints
organization_api_key = "YOUR_ORGANIZATION_API_KEY" # Organization key is only required for creating new apps and other top-level endpoints
)
# Enter a context with an instance of the API client
with onesignal.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = default_api.DefaultApi(api_client)
app = App(
name="name_example",
android_gcm_sender_id="android_gcm_sender_id_example",
gcm_key="gcm_key_example",
chrome_web_origin="chrome_web_origin_example",
chrome_key="chrome_key_example",
chrome_web_default_notification_icon="chrome_web_default_notification_icon_example",
chrome_web_sub_domain="chrome_web_sub_domain_example",
apns_env="sandbox",
apns_p12="apns_p12_example",
apns_p12_password="apns_p12_password_example",
safari_apns_p12="safari_apns_p12_example",
safari_apns_p12_password="safari_apns_p12_password_example",
apns_key_id="apns_key_id_example",
apns_team_id="apns_team_id_example",
apns_bundle_id="apns_bundle_id_example",
apns_p8="apns_p8_example",
safari_site_origin="safari_site_origin_example",
safari_icon_256_256="safari_icon_256_256_example",
site_name="site_name_example",
organization_id="organization_id_example",
additional_data_is_root_payload=True,
)
try:
# Create an app
api_response = api_instance.create_app(app)
pprint(api_response)
except onesignal.ApiException as e:
print("Exception when calling DefaultApi->create_app: %s\n" % e)
print("Status Code: %s" % e.status)
print("Response Body: %s" % e.body)
- lang: php
label: PHP SDK
source: >-
setRestApiKeyToken('YOUR_REST_API_KEY')
->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');
$apiInstance = new onesignal\client\Api\DefaultApi(
// If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
// This is optional, `GuzzleHttp\Client` will be used as default.
new GuzzleHttp\Client(),
$config
);
$app = new \onesignal\client\model\App(); //
\onesignal\client\model\App
try {
$result = $apiInstance->createApp($app);
print_r($result);
} catch (\onesignal\client\ApiException $e) {
echo 'Exception when calling DefaultApi->createApp: ', $e->getMessage(), PHP_EOL;
echo 'Status Code: ', $e->getCode(), PHP_EOL;
// getErrorMessages() flattens any error-envelope shape to a string[];
// the raw body remains on getResponseBody().
echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;
echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;
} catch (\Exception $e) {
echo 'Exception when calling DefaultApi->createApp: ', $e->getMessage(), PHP_EOL;
}
- lang: go
label: Go SDK
source: |-
package main
import (
"context"
"fmt"
"os"
"github.com/OneSignal/onesignal-go-api/v5"
)
func main() {
app := *onesignal.NewApp() // App |
configuration := onesignal.NewConfiguration()
apiClient := onesignal.NewAPIClient(configuration)
orgAuth := context.WithValue(context.Background(), onesignal.OrganizationApiKey, "YOUR_ORGANIZATION_API_KEY") // Organization API key is only required for creating new apps and other top-level endpoints
resp, r, err := apiClient.DefaultApi.CreateApp(orgAuth).App(app).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.CreateApp``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {
// ErrorMessages() flattens any error-envelope shape to a []string;
// the raw body remains on Body().
fmt.Fprintf(os.Stderr, "Error Messages: %v\n", apiErr.ErrorMessages())
fmt.Fprintf(os.Stderr, "Response Body: %s\n", apiErr.Body())
}
}
// response from `CreateApp`: App
fmt.Fprintf(os.Stdout, "Response from `DefaultApi.CreateApp`: %v\n", resp)
}
- lang: ruby
label: Ruby SDK
source: |-
require 'onesignal'
# setup authorization
OneSignal.configure do |config|
# Configure Bearer authorization: organization_api_key
config.organization_api_key = 'YOUR_ORGANIZATION_API_KEY'
end
api_instance = OneSignal::DefaultApi.new
app = OneSignal::App.new # App |
begin
# Create an app
result = api_instance.create_app(app)
p result
rescue OneSignal::ApiError => e
puts "Error when calling DefaultApi->create_app: #{e}"
puts "Status Code: #{e.code}"
# `e.error_messages` flattens any error-envelope shape to an Array;
# the raw body remains on `e.response_body`.
puts "Error Messages: #{e.error_messages}"
puts "Response Body: #{e.response_body}"
end
- lang: java
label: Java SDK
source: |-
// Import classes:
import com.onesignal.client.ApiClient;
import com.onesignal.client.ApiException;
import com.onesignal.client.Configuration;
import com.onesignal.client.auth.*;
import com.onesignal.client.model.*;
import com.onesignal.client.api.DefaultApi;
public class Example {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.onesignal.com");
// Configure HTTP bearer authorization: organization_api_key
HttpBearerAuth organization_api_key = (HttpBearerAuth) defaultClient.getAuthentication("organization_api_key");
organization_api_key.setBearerToken("YOUR_ORGANIZATION_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
App app = new App(); // App |
try {
App result = apiInstance.createApp(app);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling DefaultApi#createApp");
System.err.println("Status code: " + e.getCode());
// getErrorMessages() flattens any error-envelope shape to a List;
// the raw body remains on getResponseBody().
System.err.println("Error messages: " + e.getErrorMessages());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
- lang: csharp
label: C# SDK
source: |-
using System;
using System.Collections.Generic;
using System.Diagnostics;
using OneSignalApi.Api;
using OneSignalApi.Client;
using OneSignalApi.Model;
namespace Example
{
public class CreateAppExample
{
public static void Main()
{
Configuration config = new Configuration();
config.BasePath = "https://api.onesignal.com";
// Configure Bearer token for authorization: organization_api_key
config.AccessToken = "YOUR_ORGANIZATION_API_KEY";
var apiInstance = new DefaultApi(config);
var app = new App(); // App |
try
{
// Create an app
App result = apiInstance.CreateApp(app);
Debug.WriteLine(result);
}
catch (ApiException e)
{
Debug.Print("Exception when calling DefaultApi.CreateApp: " + e.Message );
Debug.Print("Status Code: "+ e.ErrorCode);
// e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList;
// the raw body remains on e.ErrorContent.
Debug.Print("Error Messages: " + string.Join(", ", e.ErrorMessages));
Debug.Print("Response Body: " + e.ErrorContent);
Debug.Print(e.StackTrace);
}
}
}
}
- lang: rust
label: Rust SDK
source: |-
use onesignal_rust_api::apis::configuration::Configuration;
use onesignal_rust_api::apis::default_api;
use onesignal_rust_api::models;
#[tokio::main]
async fn main() {
let mut configuration = Configuration::new();
configuration.organization_api_key_token = Some("YOUR_ORGANIZATION_API_KEY".to_string());
// Realistic values are pulled from the spec's `example:` fields where present.
let app: models::App = todo!();
match default_api::create_app(&configuration, app).await {
Ok(resp) => println!("{:?}", resp),
Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {
// `e.error_messages()` flattens any error-envelope shape to a Vec;
// the raw response remains on the ResponseError variant.
eprintln!("create_app failed: {:?}", e.error_messages());
}
Err(e) => eprintln!("create_app failed: {:?}", e),
}
}
components:
schemas:
BasicErrorResponse:
type: object
properties:
errors:
type: array
items:
type: string
description: One or more human-readable error messages.
success:
type: boolean
description: >-
Present (and `false`) on some endpoints (notifications, templates,
segments). Not emitted by every endpoint.
reference:
type: array
items:
type: string
description: >-
Documentation URL fragments related to the error. Only emitted by
the API-key auth error helpers.
````