The methods below require the OneSignal SDK versions 3 & 4.

It is recommended to upgrade to our latest version 5 SDKs for User Model APIs.

See Update to User Model for migration steps.

OneSignal supports a higher security method known as Identity Verification. This helps prevent users from impersonating one another by generating a user-specific token on your server, if you have one.

Enabling Identity Verification applies to:

  • Adding Email and SMS records into OneSignal AND associated tags.
  • Setting external_user_id for any record across all channels (Push, Email, SMS)

It can be enabled in the Dashboard > Settings > Keys & IDs

Once enabled or disabled, this will take up to 10 minutes to process.

We highly recommend enabling identity verification for apps and websites that use setting external_user_ids and/or Email Messaging. For apps and websites that are ‘backendless’ and do not run their own servers, we suggest either creating a minimal server that just verifies users, saving the OneSignal User ID records to your database, or avoid sending sensitive information in user tags and notifications.

Auth Hash Generation

Auth hashes are expected to be a HMAC on a SHA-256 of the OneSignal REST API Key and the <protected_field_value>.

Example Auth Hash Generation Code

When identity verification is enabled, OneSignal will look for a SHA-256 hash of a user’s email address or external user identifier from your server. See the following code examples for how to generate these hashes on your server:

OpenSSL::HMAC.hexdigest('sha256', ONESIGNAL_API_KEY, identifier)
OpenSSL::HMAC.hexdigest('sha256', ONESIGNAL_API_KEY, email_address)

SDK setEmail Method

Your backend can generate an email authentication token and send it to your app to include in the setEmail method.

var emailAddress = "[email protected]";
var emailAuthHash = "..."; // Email auth hash generated from your server
OneSignal.push(function() {
  OneSignal.setEmail(emailAddress, {
   emailAuthHash: emailAuthHash
  });
});

SDK setSMSNumber Method

Your backend can generate an SMS authentication token and send it to your app to include in the setSMSNumber method.

String smsNumber = "+123456789";
String smsAuthHash = "..."; // SMS auth hash generated from your server
OneSignal.setSMSNumber(smsNumber, smsAuthHash, new OneSignal.OSSMSUpdateHandler() {
  @Override
  public void onSuccess(JSONObject result) {
    // SMS successfully synced with OneSignal
  }

  @Override
  public void onFailure(OneSignal.OSSMSUpdateError error) {
  	// Error syncing SMS, check error.getType() and error.getMessage() for details
  }
});

SDK setExternalUserId Method

Your backend can generate an email authentication token and send it to your app to include in the setExternalUserId method.

let externalUserId = "123456789" // You will supply the external user id to the OneSignal SDK
let externalUserIdAuthHash = "..."; // Identifier auth hash generated from your server

OneSignal.push(function() {
  OneSignal.setExternalUserId(externalUserId, externalUserIdAuthHash);
});

Updating Devices with REST API

If you enabled Identity Verification and call the Add a device or Edit device endpoint (api/v1/players), the request must contain the external_user_id_auth_hash or identifier_auth_hash parameters.

If you are adding or updating the external_user_id on a non-email device (device_type != 11), you must use the external_user_id_auth_hash parameter.

If you are adding or updating the email (identifier parameter && device_type = 11), then any field being updated will need the identifier_auth_hash (or email_auth_hash for backwards compatibility) value.

Removing External User ID

To remove an external_user_id from a device record with Identity Verification enabled, you can set it to an empty string with the auth hash based on the existing external_user_id value before removal.