Application-Level Clients

Application-level OAuth2 clients allow your application to initiate authentication requests with Wristband. Depending on the client type you choose, they can authenticate both human users and non-human identities (such as machines or services).

You can create the following types of clients at the application level:

• Backend Server
• Native
• Machine-to-Machine

A single application can support multiple client types to accommodate different authentication use cases. Additionally, any client configured at the application level can authenticate users across all tenants belonging to that application.

Example Scenarios

Web Application + Mobile

Imagine an application accessible through three different interfaces:

• A Next.js web application served in the browser
• An Android mobile app
• An iOS mobile app

To support this, you would configure one unique OAuth2 client for each interface. Each of these three clients has the built-in capability to initiate authentication requests for all users under that application

Backend Microservices

For microservice architectures, assign an application-level Machine-to-Machine (M2M) client to each service to handle secure service-to-service authentication.

---

Managing Application Clients With Wristband's Dashboard

The Wristband dashboard offers a complete set of tools to manage your application's clients. The sections below detail the core client management features available in the dashboard.

Adding a Client

1. In the Application View, select OAuth2 Clients from the left navigation menu.
2. Click the + Add Client button.

1. Select a client type (Backend Server, Machine (M2M), or Native).
2. Enter a Name for the client.
3. Click the Create button.

• View your newly generated clientId and clientSecret (applicable only to Backend Server and Machine (M2M) types).

• Securely save the plaintext secret immediately. Wristband only stores a one-way hash of the secret, meaning it cannot be retrieved or displayed again after you leave this screen.

When a client is first created, it has no default permissions or routing paths. Depending on your client type, you must configure these settings before initiating requests:

• Roles: Required for Backend Server and Machine-to-Machine (M2M) clients to grant authorization.
• Redirect URIs: Required for Backend Server and Native clients to route authentication responses.

Review the sections below to learn how to edit your client's configuration.

Editing an Existing Client

1. Select OAuth2 Clients from the left navigation menu.
2. Click the name of the client you wish to update from the clients table.

Configuring Client Settings

The Client Settings section allows you to configure the client's Name, Description, and Redirect URIs.

Expand the Advanced Settings panel to reveal additional configuration options.

• Enable Refresh Token Grant Type: When enabled, this client can exchange refresh tokens for new access tokens to keep user sessions alive seamlessly.

• Enable Client Credentials Grant Type: Allows the client to use the Client Credentials grant to call Wristband's APIs on its own behalf. This setting applies strictly to Backend Server clients, as Native clients cannot maintain a client secret.
• Restrict Time to Complete Login: Enforces a fixed time window for users to complete their login. If disabled, the login flow does not expire, and users have unlimited time to authenticate.
• How Long Should Users Have to Complete Login: Available only when "Restrict Time to Complete Login" is enabled. The maximum allowed expiration time is 60 minutes.
• Login URL: Optionally overrides your application's global Login URL. When configured, authentication flows initiated by this specific client will redirect users to the client-level Login URL instead of the application-level fallback.

Configuring JWT Settings

Scroll down to the JWT Settings section to configure the validity duration of tokens issued to this client.

Assigning Roles to a Client

Scroll down to the Roles section and use the multi-select dropdown to add or modify the roles assigned to this client.

Validating a Client's Secret

1. Scroll down to the Client Secret Settings section.
2. Enter the secret value you want to test.
3. Click the Validate button to check its status.

Rotating a Client's Secret

1. Scroll down to the Client Secret Settings section.
2. Locate the Primary Client Secret.
3. Click the Rotate button next to it.

Secret Rotation Mechanics:

1. New Secret: A new primary secret is generated immediately.
2. Current Secret: Becomes the secondary secret so your application experiences zero downtime.
3. Existing Secondary Secret: If you already have a secondary secret, it is permanently deleted.

To confirm: Type "rotate" and click Rotate.

Your new client secret will be displayed. Record it securely at this time, as it cannot be shown again.

1. Verify that your new primary secret has been rolled out to all environments.
2. Go to Client Secret Settings.
3. Click Delete next to the Secondary Client Secret to remove it permanently.

To confirm: Type "delete" in the text field and click the Delete button.

Deleting a Client

1. Scroll to the bottom of the Edit Client page to the Delete this Client section.
2. Click the Delete button.

Deleting a client is permanent and cannot be undone. To confirm this action, type "delete" in the text field and click the Delete button.

Generating Access Tokens

1. Scroll down to the Generate Access Tokens section on the Edit Client page.
2. Paste your client secret into the field.
3. Click the New Token button to instantly generate an access token for manual testing in tools like cURL or Postman.

Your access token will be displayed below. Copy it somewhere safe immediately, as it cannot be shown again.