Core Concepts

Understanding the key entities in NativeSuite and how they relate to each other.

Apps

An App is the top-level entity that represents your product on NativeSuite. Each app has:

• A name and slug (unique identifier)
• Credentials for authenticating API calls from your backend to NativeSuite
• Optional metadata: website, support email, privacy policy, terms of service

You can create multiple apps under one workspace — useful if you have multiple products.

Data Sources

A Data Source is a connection to one of your REST API endpoints. It defines:

• Endpoint URL — where to fetch data from
• HTTP method and headers — how to call your API
• Authentication — how NativeSuite authenticates with your API (separate from how your end users authenticate)
• Response mapping — which fields from the JSON response to make available for widgets

Data sources are shared across all releases of an app. When you update a data source, all widgets using it get the updated data.

Authentication Providers

An Authentication Provider defines how your end users prove their identity so NativeSuite can fetch their personalized data. Three types:

Type	How It Works	Best For
API Key	User enters a key you provide them	Simple integrations, service dashboards
Username & Password	User logs in with credentials from your app	Apps with existing user accounts
OAuth Redirect	User is redirected to your web-based login flow	Apps with web-based SSO or OAuth

Each app can have multiple auth providers configured.

Releases

A Release is a versioned snapshot of your widgets and notification templates. Releases follow a lifecycle:

Draft → Testing → Review → Live → Archived

• Draft — You're building. Add widgets, notification templates, configure everything
• Testing — Invite testers to try it on real devices
• Review — Submit for NativeSuite team review before going public
• Live — Available to all users
• Archived — Retired from active use

Each release has a version (e.g., 1.0.0), name, description, logo, and category.

Why releases?

Releases let you iterate safely. You can build v2.0 in draft while v1.0 is live. Testers see the draft; users see the live version. No disruption.

Widgets

A Widget is a native UI element that displays data from your API on the user's home screen. Each widget is built from a template and configured with:

• Data source — where to pull data from
• Field mapping — which data fields map to which template slots
• Style — colors, layout options specific to the template
• Sizes — which widget sizes to support (compact, standard, expanded)
• Visibility conditions — optionally show/hide based on data field values

Widgets belong to a release. When you create a new release, you can add new widgets or modify existing ones without affecting the live version.

Widget Templates

NativeSuite provides seven built-in widget templates:

Template	Description	Example Use Case
Stat	Single metric with label and optional change indicator	Revenue, user count, uptime
Card	Title, body, optional tag	Alerts, order updates, status messages
List	Ordered items with status indicators	Tasks, recent orders, notifications
Table	Rows and columns	Service health, leaderboards
Chart	Bar chart with labels	Weekly signups, daily revenue
Image	Image from URL with optional caption	Product photos, charts from your API
Text	Formatted text block	Daily digests, summaries

Notification Templates

A Notification Template defines the structure of a push notification. Templates use syntax for dynamic content:

Title: Order #{{order_id}} shipped
Body: {{item_count}} items on the way to {{city}}, {{country}}

Templates belong to a release. Your backend sends the variable values when triggering a notification via the API.

Testers

Testers are users you invite to try your app before it goes live. They:

• Receive an email invitation
• Accept the invite in the NativeSuite mobile app
• Can see releases in Testing status
• Help you validate widgets and notifications on real devices

App Credentials

Each app has a credential (API key + secret) used to authenticate requests from your backend to NativeSuite — for example, when sending push notifications. You can rotate credentials from the dashboard if compromised.

Request Signing

NativeSuite signs requests to your API endpoints using HMAC. This lets you verify that incoming requests actually come from NativeSuite, not a third party. See the Request Signing guide for implementation details.

How It All Connects

Workspace
 └── App
      ├── Data Sources (your API endpoints)
      ├── Auth Providers (how users authenticate)
      ├── Credentials (your app's API key for NativeSuite)
      ├── Testers (beta users)
      └── Releases
           ├── Widgets (template + data source + field mapping)
           └── Notification Templates (title/body patterns)