Server REST API Reference
Log InSign Up

Update an app

put https://api.onesignal.com/apps/

Updates the name or configuration settings of an existing OneSignal app

Overview

Use this API to update an existing OneSignal app. This is helpful if you need to update multiple apps and don't want to login to the dashboard to do so. You can use this API to move apps between existing organizations, or including a blank value for organization_id will create a new organization for the app to be moved to. The push platform configuration settings for web and mobile can also be populated or updated using this API.

See Apps & Organizations for more about OneSignal apps and organizations.

How to use this API

Using your Organization API key (available in Organizations > Keys & IDs) you can update an existing OneSignal app. The Organization API key is not the same as the REST API key.

You can use an existing Organization ID to move the app to an organization or leave the value blank to create a new organization to which the app will be moved.

You can include some or all of the parameters for your apps push platform settings in order to set up or change push settings, but the email and SMS platform settings must be configured through the OneSignal dashboard. See below for a list of platform specific settings for web, Android, and iOS push notifications:

Web push configuration

Required: site_name, chrome_web_origin, safari_site_origin

Use site_name to set the specific origin URL for your website, and include https://. You should also set the chrome_web_origin and safari_site_origin to the same value and all three must be set in the same request.

Recommended: chrome_web_default_notification_icon, safari_icon_256_256

Use the chrome_web_default_notification_icon and safari_icon_256_256 parameters to set the default icon for web push notifications. These parameters should be set to the URL of a 256x256px png image. See our web push setup guide for more details and examples of where this icon is displayed.

Other : safari_apns_p12, safari_apns_p12_password

You can set your push notification p12 certificate file for Safari Push Notifications using these parameters. The value for safari_apns_p12 should be your p12 certificate converted to base64 encoded format and the value for safari_apns_p12_password should be the password for the same file. For details on how to generate a p12 file, please see our p12 guide .

These parameters are entirely optional and they if not provided we will assign a p12 to your account for you. If using your own p12, you will need to include both the base64 encoded certificate and the password in the same request.

Android mobile push configuration

Required: fcm_v1_service_account_json

This parameter should be set to your FCM Service Account Private Key JSON file, converted to base64 format. See our Android: Firebase Credentials guide for details on how to generate the Private Key JSON file.

iOS mobile push configuration

iOS mobile push can be configured using either a p8 or a p12 authentication.

Required if using p8: apns_key_id, apns_team_id, apns_bundle_id, apns_p8

The apns_p8 should be your p8 key file converted to base64 encoded format. you can download your p8 key and retrieve your apns_key_id, apns_team_id, and apns_bundle_id from your Apple developer account by following our p8 configuration guide.

apns_p8 example:

  1. Go to https://www.base64encode.org
  2. Use the "Encode files to Base64 format" and upload the p8 file. Then press the "ENCODE" button and download the file.
    1. This will change the p8 format from: 
      -----BEGIN PRIVATE KEY-----
...
your-4-lines-of-text
...
...
\-----END PRIVATE KEY-----
    2. To this format: LS0tLS1CRUdJTiBQ-some-random-string-of-characters-gS0VZLS0tLS0=
  3. Set that as the value for apns_p8.

Required if using p12: apns_p12, apns_p12_password

The value for safari_apns_p12 should be your p12 certificate converted to base64 encoded format and the value for safari_apns_p12_password should be the password for the same file. For details on how to generate a p12 file, please see our p12 guide .

Other : apns_env, additional_data_is_root_payload

Use apns_env to specify whether this is a production or sandbox environment (leave blank to default to production). Setting additional_data_is_root_payload to true allows iOS push notification data values to be added to the root of the aps payload when sent to the iOS device (omit this value unless you use other push SDKs or not using OneSignal SDK methods to read the payload).


📘

Updating Some Platforms Requires All Attributes To Be Set

Updating some platforms like Safari web push requires all parameters to be set (even if they are unchanged) in order for the update to be processed.

  • To update only your app name, you can pass in only a new app name parameter.
  • To update Android, be sure to pass in gcm_key.
  • To update Chrome Apps & Extensions, be sure to pass in chrome_key.
  • To update Chrome web push, be sure to pass in chrome_web_origin.
  • To update Safari web push, you must pass in all of these parameters: safari_apns_p12, safari_apns_p12_password, site_name, and safari_site_origin. Most users use our auto-generated Safari web ID. If you use our auto-generated Safari web ID, please set safari_apns_p12 to "" and safari_apns_p12_password to "".
  • To update iOS, you must pass in apns_env.

Body parameters

name

Type string

Description

The name of your OneSignal app, to be displayed in the OneSignal dashboard and when retrieving the app using the view app or view an app endpoints. Can be updated later.

organization_id

Type string

Description

The Organization ID in which to include this app. If no ID provided, the app will be added to a newly created Organization in your account.

fcm_v1_service_account_json

Type string

Description

Android: Required if using Android push notifications. Your FCM Service Account JSON file converted to base64 format. See Android: Firebase Credentials for details.

chrome_web_origin

Type string

Description

Chrome (All Browsers except Safari): Required if using web push. The URL to your website. Must use https:// and be the specific origin.

chrome_web_default_notification_icon

Type string

Description

Chrome (All Browsers except Safari): Your default notification icon as a 256x256px .png URL.

site_name

Type string

Description

All Browsers: Recommended if using web push. The Site Name. Requires both chrome_web_origin and safari_site_origin to be set in the same request when setting or updating it.

safari_site_origin

Type string

Description

Safari: Recommended if using web push. The URL to your website. Must use https:// and be the specific origin.

safari_apns_p12

Type string

Description

Safari: Your push notification p12 certificate file for Safari Push Notifications, converted to base64 encoded format. If not provided, then we will assign one.

safari_apns_p12_password

Type string

Description

Safari: Password for the safari_apns_p12 file. Omit if no password.

safari_icon_256_256

Type string

Description

Safari: Your default notification icon as a 256x256px .png URL.

apns_p12

Type string

Description

iOS: Required if using p12 APNS Authentication. Your apple push notification p12 certificate file, converted to Base64 en

apns_p12_password

Type string

Description

iOS: Required if using p12 APNS Authentication. Password for the apns_p12 file. Omit if no password.

apns_env

Type string

Description

iOS: Indicates the APS Environment Entitlement. Omit this field for Production environment (App Store & Test Flight builds). Or set either sandbox or production

apns_key_id

Type string

Description

iOS: Required if using p8 APNS Authentication.

apns_team_id

Type string

Description

iOS: Required if using p8 APNS Authentication.

apns_bundle_id

Type string

Description

iOS: Required if using p8 APNS Authentication.

apns_p8

Type string

Description

iOS: Required if using p8 APNS Authentication. Must be base64 encoded format.

additional_data_is_root_payload

Type boolean

Description

iOS: Allows iOS push notification data values to be added to the root of the aps payload when sent to the iOS device. Only used for special cases. Omit this value unless you use other push SDKs or not using OneSignal SDK methods to read the payload.

Language