Skip to main content

Connect to OneSignal

Connect OneSignal to Retool and send push notifications, manage devices, and track messaging campaigns.

OneSignal is a customer engagement platform for sending push notifications, in-app messages, email, and SMS.

What you can do with OneSignal in Retool​

After you create a OneSignal resource in Retool, you can:

  • Send push notifications to devices registered with your OneSignal app.
  • Register and manage devices, including tags and external user IDs.
  • View notification delivery history and outcomes.
  • Manage OneSignal apps and segments.

Before you begin​

To connect OneSignal to Retool, you need the following:

  • OneSignal REST API key: Required for most OneSignal API endpoints, such as sending notifications and managing devices. Retrieve it from your OneSignal app's Keys & IDs settings.
  • OneSignal User Auth Key: Required only if you need to manage OneSignal apps themselves (the /apps/ endpoints). Retrieve it from your OneSignal account settings.
  • Retool permissions: Ability to create and manage resources in your organization.

Create a OneSignal resource​

Follow these steps to create a OneSignal resource in Retool.

1. Create a new resource​

In your Retool organization, navigate to Resources in the main navigation and click Create new → Resource. Search for OneSignal and click the OneSignal tile to begin configuration.

2. Configure general settings​

Specify a name and description for the resource that indicates which OneSignal app or environment it connects to. The description provides more context to users and Assist about how to use the resource.

OneSignal resource configuration form.

Resource name and description​

Choose a name and description that indicate which OneSignal app or environment the resource connects to.

Example nameExample description
OneSignal productionSends push notifications to production mobile app users.
OneSignal stagingUsed to test notification content and targeting before release.

3. Configure authentication​

OneSignal authenticates requests using two independent API keys. Neither field is strictly required to save the resource, but you need at least one populated to run queries, depending on which endpoints you use.

REST API key​

Used for most OneSignal endpoints, including sending notifications and managing devices. Generate this key from your OneSignal app's Keys & IDs page.

Example
os_v2_app_••••••••••••••••••••••••••••••••

User Auth key​

Used only for endpoints under /apps/, such as creating or updating OneSignal apps themselves. Most notification and device operations don't require this key.

Example
••••••••••••••••••••••••••••••••
Credential storage

Retool encrypts both key fields automatically. Enter the values directly in the resource configuration rather than storing them elsewhere.

4. Configure advanced options​

Outbound region​

If your organization uses outbound regions, select the region that should be used for requests to OneSignal. This controls which geographic region your requests originate from.

5. Save the resource​

OneSignal doesn't support testing the connection before saving, so click Create resource directly to save your OneSignal resource. Verify your credentials by running a query, such as viewing your OneSignal apps, after the resource is saved. The resource is now available to use in apps, workflows, and agent tools across your Retool organization.

Interact with OneSignal data​

Once you've created a OneSignal resource, you can interact with OneSignal data using Retool.

Switch to the new app builder

Retool recommends using the new app builder so you can use natural language to build React-based apps using AI.

Best practices​

Follow these best practices to maintain the security of your OneSignal resource.

  • Use configuration variables: Store any OneSignal key values you need inside a query (rather than the resource's own credential fields) in configuration variables or secrets.
  • Use HTTPS only: Retool always connects to OneSignal over HTTPS to encrypt data in transit and protect authentication credentials.
  • Rotate credentials regularly: Follow OneSignal's recommendations for REST API key and User Auth key rotation.
  • Use resource environments: Configure multiple resource environments to maintain separate keys for production, staging, and development OneSignal apps.
  • Apply least privilege: Only configure the User Auth key if you need to manage OneSignal apps themselves. Most integrations only need the REST API key.