> ## 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.
# Update an app
> Use to update the name or push platform configuration of an existing app. This guide explains required parameters and platform-specific update rules
## Overview
Use this API to programmatically update an existing OneSignal app. This is useful 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 change your FCM Service Account JSON file to a different Firebase project, your Android Subscriptions tied to the current project will become invalid. They will not be able to receive push notifications until they open your app again with this new FCM Service Account JSON file.
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 help Base64 encoding 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). **You will likely never need to update these parameters if set correctly during app creation**:
* `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). **These must be updated every year which is why we recommend using p8 authentication**:
* `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 PUT /apps/{app_id}
openapi: 3.1.0
info:
title: api.onesignal.com
version: '11.6'
servers:
- url: https://api.onesignal.com
security:
- {}
paths:
/apps/{app_id}:
put:
summary: Update an app
description: >-
Use to update the name or push platform configuration of an existing
app. This guide explains required parameters and platform-specific
update rules
operationId: update-an-app
parameters:
- name: Content-Type
in: header
required: true
schema:
type: string
default: application/json
- name: app_id
in: path
description: >-
Your OneSignal App ID in UUID v4 format. See [Keys &
IDs](/docs/en/keys-and-ids).
schema:
type: string
default: YOUR_APP_ID
required: true
- 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
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
fcm_v1_service_account_json:
description: >-
Your FCM Service Account JSON file for Android push
notifications. See [Android: Firebase
Credentials](/docs/android-firebase-credentials).
type: string
fcm_sender_id:
description: The FCM Sender ID associated with your Firebase project.
type: string
chrome_web_key:
description: >-
Web push VAPID public key for Chrome web push
notifications.
type: string
chrome_web_origin:
description: >-
The HTTPS origin URL for your website. Required for web
push notifications.
type: string
chrome_web_gcm_sender_id:
description: The GCM Sender ID used for web push notifications.
type: string
chrome_web_default_notification_icon:
description: >-
The full HTTPS URL to your default notification icon.
Should be a 256x256px PNG.
type: string
chrome_web_sub_domain:
description: >-
The OneSignal subdomain for web push if not using your own
origin.
type: string
apns_env:
description: >-
The APNS environment: `production` or `development`. See
[iOS SDK Setup](/docs/ios-sdk-setup).
type: string
apns_certificates:
description: >-
The APNS p12 certificate for iOS push notifications. See
[p12 APNS
Authentication](/docs/ios-p12-generate-certificates).
type: string
apns_p8:
description: >-
The APNS p8 token key for iOS push notifications. See [p8
Token-based connection to
APNS](/docs/ios-p8-token-based-connection-to-apns).
type: string
apns_team_id:
description: The Apple Team ID associated with your APNS credentials.
type: string
apns_key_id:
description: The APNS Key ID for p8 token-based authentication.
type: string
apns_bundle_id:
description: >-
The iOS app Bundle ID associated with your APNS
credentials.
type: string
site_name:
description: >-
The name of your website, used for web push notification
titles.
type: string
'403':
description: >-
Forbidden. The Authorization key does not have permission to update
this app, or the requested change violates the organization's policy
(e.g., transferring an app to another organization).
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorResponse'
example:
errors:
- You do not have permission to update this app.
'404':
description: >-
App not found, or the target organization (when transferring) was
not found.
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorResponse'
example:
errors:
- Couldn't find app with id =
'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);
// string | An app id
const appId: string = "00000000-0000-0000-0000-000000000000";
// 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.updateApp(appId, 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("updateApp 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_id = "00000000-0000-0000-0000-000000000000" # An app id
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:
# Update an app
api_response = api_instance.update_app(app_id, app)
pprint(api_response)
except onesignal.ApiException as e:
print("Exception when calling DefaultApi->update_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_id = '00000000-0000-0000-0000-000000000000'; // string | An app
id
$app = new \onesignal\client\model\App(); //
\onesignal\client\model\App
try {
$result = $apiInstance->updateApp($app_id, $app);
print_r($result);
} catch (\onesignal\client\ApiException $e) {
echo 'Exception when calling DefaultApi->updateApp: ', $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->updateApp: ', $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() {
appId := "00000000-0000-0000-0000-000000000000" // string | An app id
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.UpdateApp(orgAuth, appId).App(app).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.UpdateApp``: %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 `UpdateApp`: App
fmt.Fprintf(os.Stdout, "Response from `DefaultApi.UpdateApp`: %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_id = '00000000-0000-0000-0000-000000000000' # String | An app id
app = OneSignal::App.new # App |
begin
# Update an app
result = api_instance.update_app(app_id, app)
p result
rescue OneSignal::ApiError => e
puts "Error when calling DefaultApi->update_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);
String appId = "00000000-0000-0000-0000-000000000000"; // String | An app id
App app = new App(); // App |
try {
App result = apiInstance.updateApp(appId, app);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling DefaultApi#updateApp");
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 UpdateAppExample
{
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 appId = "00000000-0000-0000-0000-000000000000"; // string | An app id
var app = new App(); // App |
try
{
// Update an app
App result = apiInstance.UpdateApp(appId, app);
Debug.WriteLine(result);
}
catch (ApiException e)
{
Debug.Print("Exception when calling DefaultApi.UpdateApp: " + 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_id: &str = "00000000-0000-0000-0000-000000000000";
let app: models::App = todo!();
match default_api::update_app(&configuration, app_id, 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!("update_app failed: {:?}", e.error_messages());
}
Err(e) => eprintln!("update_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.
````