Setting Up a Demo App
This guide helps you set up a Wristband demo app to get started and understand how to use Wristband.
If you are just getting started with Wristband, this guide will walk you through how to set up one of the Wristband demo apps to help you understand how to work with Wristband.
The Demo App Modal
Start your Wristband journey by setting up a demo app on your local machine. These apps serve as templates for integrating Wristband into your project—feel free to copy the code directly!
After logging into the Wristband dashboard, click the "Add Demo App" button on the home page to start the guided setup.
Home Page: Add Demo App Button
Demo App Environment
Regardless of the type of demo app you create, they will always be configured for a development environment, meaning that production validations are not enabled.
Choosing Your Subject Kind
First, you'll be asked to define the type of subject requiring authentication for the application. This decision depends on whether access tokens will be issued to human users or automated backend services.
Choose whether users or machines will authenticate.
Authenticating Users
Selecting "Humans" as the authentication subject means human users will authenticate via Wristband-hosted login pages. They’ll receive an access token, ID token with OpenID user attributes, and a refresh token for seamless session continuity without re-authentication.
Authenticating Machines
Choosing "Machines" as the authentication subject designates an automated service or system for authentication. In this setup, the service makes an API call to the Wristband Token Endpoint at startup to obtain an access token. Since this is a machine-to-machine interaction, no ID token or refresh token is issued.
Choosing Your Client Type
After selecting the authentication subject, you'll be prompted to choose your preferred framework. This step involves selecting an OAuth2 client type tailored to your chosen framework or language. The options on this screen will dynamically adjust based on your previous selection. To see the full list of currently supported frameworks, check out Example Apps page.
Available Client Frameworks
We're actively expanding our demo app options to include more languages and frameworks. Let us know if you have a specific request!
Choose your OAuth2 client type.
Choosing Your URL Type
From here, you'll be asked to specify the type of URLs you'd like to use for the demo application. These URLs refer to the endpoints that end-users will access to reach your application, which should not be confused with the URLs used by the demo app to redirect and make API requests to the Wristband platform.
Choose the type of URLs your application will use.
Localhost
Localhost is the default choice for most developers when testing a demo app on their local machine. For instance, once you've configured and launched the demo app, you can access it using a URL like http://localhost:6001. The localhost URLs will be used in two locations within Wristband:
| Entity | Field | Example |
|---|---|---|
| Application | loginUrl | http://localhost:6001/api/auth/login |
| OAuth2 Client | redirectUris | http://localhost:6001/api/auth/callback (This field can take multiple values, but the demo app creation will only supply one value.) |
For user authentication, Wristband-hosted pages for this URL type won't utilize tenant subdomains. Instead, they will rely on the tenant_domain query parameter being passed in when accessing pages such as the Tenant-level Login page.
Demo application that uses localhost URLs
Vanity Domains
If you want to test vanity domains on your local machine, including tenant subdomains, you can opt for the Vanity Domains URL type. The advantage of this approach is that it closely replicates your production environment in terms of URLs and routing.
This is an advanced setup for local testing and entails additional configuration on your local machine to manage DNS resolution. For instance, on a Mac, you might use a tool like dnsmasq to handle DNS resolution. Alternatively, there are other solutions that can facilitate this, like ngrok, Cloudflare Tunnels, and others.
Tenant subdomains are automatically incorporated into any generated URLs using the tenant domain wildcard token ({tenant_domain}). Wristband intelligently resolves this token to the specific tenant under which a user is authenticating. The resulting URLs within Wristband will appear as follows:
| Entity | Field | Example |
|---|---|---|
| Application | loginUrl | http://{tenant_domain}.app.demo.com:6001/api/auth/login |
| OAuth2 Client | redirectUris | http://{tenant_domain}.app.demo.com:6001/api/auth/callback(This field can take multiple values, but the demo app creation will only supply one value.) |
M2M Demo App URLs
Demo apps employing a client framework for M2M client types are limited to running on localhost URLs, regardless of which URL type is selected.
Provisioning the Demo App
Once you've made all the necessary selections for your demo app configuration, you'll receive a preview of the different entities that Wristband will create to support your demo app. At this point, you can simply click the "Create" button to automatically provision all the entities as previewed.
Copying Values Into Environment Variables
After a successful creation, you will encounter two elements: a link to the GitHub repository associated with the chosen demo app and a set of string values available for copying. Before closing the modal, you should proceed to the GitHub repository and clone the project.
Values to copy into the environment variable configuration of the demo app.
Once you've cloned the repository, you'll copy and paste the string values from the modal into the .env file located within your demo app repository. The following are possible values you will see on this screen, depending on which demo app configuration you selected.
| Name | Description | Appears For |
|---|---|---|
| Application Domain | String value representing the Application-level vanity domain for your Wristband application. This base URL is used when redirecting to Wristband during authentication flows and when making API requests to Wristband. | All demo apps. |
| Domain Format | String value representing the type of URL format the demo application should use when attempting to interact with it. Possible values are LOCALHOST and VANITY_DOMAIN. | All demo apps that do not use a M2M client type. |
| Client ID | String value representing the unique identifier assigned to your demo application's OAuth2 Client. | All demo apps. |
| Client Secret | String value representing the confidential, shared key between the demo application's OAuth2 Client and Wristband. | All demo apps that do not use a Single Page Application client type. |
Below is an example demonstrating where these values should be inserted:
Example of the environment variable configuration for a demo app.
And that's it! From here, you can follow the steps in the demo app's GitHub README file on how to build and run the demo app locally.
Updated about 1 month ago