Application-Level Clients

Application-level clients are used by your application to initiate authentication requests to Wristband. These clients are meant to authenticate users accessing your application. However, you can also create application-level Machine-to-Machine (M2M) clients to authenticate autonomous processes without user interaction.

All three client types can be created at the application level:

• Backend Server
• Native
• Machine-to-Machine

Example Scenarios

Web Application + Mobile

Let's imagine you have an application that your users can access by the following methods: a web application in their browser served by NextJS, an Android app, and an iOS app. You would configure an OAuth2 Client for each of those three different interfaces to your application. Each OAuth2 Client can initiate authentication requests for all users under the application.

Backend Microservices

If your application is implemented using a microservice architecture, you can create an application-level M2M client for each microservice to authenticate requests between services.

---

Managing Application Clients With Wristband's Dashboard

The Wristband dashboard provides a comprehensive set of tools for managing your application's clients. The sections below highlight the dashboard's core client management features.

Adding a Client

To add a new client, go to "OAuth2 Clients" from the left navigation menu in Application View, then click the "+ Add Client" button.

Select a client type (Backend Server, Machine (M2M), or Native), enter a name for the client, and then click the "Create" button.

If you selected Backend Server or Machine (M2M), you'll be shown the client's clientId and clientSecret. Wristband only stores the hashed version of the secret, so record the plaintext secret securely at this time since it won't be shown again.

When a client is first created, it has no roles assigned yet (relevant for Backend Server and Machine-to-Machine clients), and no Redirect URIs are set yet (relevant for Backend Server and Native clients). To configure either of these, you'll need to edit the client's configuration, covered in the sections below.

Editing an Existing Client

You can edit a client by clicking "OAuth2 Clients" from the left navigation menu and then clicking the client you want to edit from the clients table.

Configuring Client Settings

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

Expanding "Advanced Settings" reveals additional configuration. This section never appears for Machine-to-Machine clients since they don't have a login flow.

• Enable Refresh Token Grant Type: Allows this client's users to obtain new access tokens using a refresh token instead of re-authenticating. Off by default.
• Enable Client Credentials Grant Type: Allows this client to authenticate itself directly using the Client Credentials grant, letting it call Wristband's APIs on its own behalf. Applies to Backend Server clients only, since Native clients can't authenticate themselves. Off by default.
• Restrict Time to Complete Login: Whether login must be completed within a fixed time window. Off by default, meaning users have unlimited time to complete login.
• How Long Should Users Have to Complete Login: Can only be configured once "Restrict Time to Complete Login" is enabled. Max expiration: 60 minutes.
• Login URL: Optionally overrides your application's Login URL. Users who log in to the application through this particular client can have a different experience than when using the Login URL configured in Application Settings.

Configuring JWT Settings

To configure how long the tokens issued to this client remain valid, scroll down to the "JWT Settings" section.

Assigning Roles to a Client

To assign roles to the client, scroll down to the "Roles" section. There, you'll see a multi-select dropdown that can be used to modify the roles assigned to the client.

Validating a Client's Secret

If you're unsure whether a client secret value you have is still valid, scroll down to the "Client Secret Settings" section, enter your secret value, and click the "Validate" button.

Rotating a Client's Secret

To rotate a client's secret, scroll down to the "Client Secret Settings" section and click the "Rotate" button next to the Primary Client Secret.

Rotating secrets generates a new primary secret in place of the current one (if one already exists). The current secret becomes the secondary client secret, and both remain valid for authorizing the client. If a secondary secret already exists, it will be permanently deleted.

To confirm, type "rotate" and click the "Rotate" button.

You'll then be shown the new client secret. Record it securely, since it won't be shown again.

Once the new secret has been rolled out everywhere it's needed, you can permanently remove the old secondary secret by clicking "Delete" next to the Secondary Client Secret.

Deleting a secondary secret can't be undone, and it immediately stops working for authorizing the client. To confirm, type "delete" and click the "Delete" button.

Deleting a Client

Scroll to the bottom of the Edit Client page to the "Delete This Client" section, then click the "Delete" button. Deleting a client will stop any users (or machines, depending on your client type and configuration) from accessing your application through it.

Deleting a client is permanent and can't be undone. To confirm, type "delete" and click the "Delete" button.

Generating Access Tokens

If you want to test calling Wristband APIs manually with tools like cURL or Postman, you can generate an access token for the client directly from the Edit Client page. Scroll down to the "Generate Access Tokens" section, paste in the client secret, and click the "New Token" button.

You'll be shown the access token. Copy it somewhere safe, since it won't be shown again.