Tenant-Level Clients

Creating clients at the tenant level, rather than the application level, isolates them from every other tenant in your application. Currently, only Machine-to-Machine (M2M) clients can be created at the tenant level, and they authenticate by calling Wristband's Token Endpoint directly using the client_credentials grant.

Tenant-level M2M clients are intended to be used by your customers to acquire an access token for calling your application's APIs, which your application then verifies in the request to authenticate the tenant clients. As confidential clients, they have a unique client ID and secret, which your customer must store securely on their side.

---

Managing Tenant Clients With Wristband's Dashboard

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

Adding a Client

To create the M2M client, enter Tenant View for your customer's tenant, then click "OAuth2 Clients" from the left navigation menu. Enter a name for the client and click the "Create Client" button.

After the client is created, you'll be shown the 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. Share both values with your customer through a secure channel.

Editing an Existing Client

You can edit a tenant client by entering Tenant View for your customer's tenant and clicking "OAuth2 Clients" from the left navigation menu. Then, click the client you want to edit from the clients table.

Configuring Client Settings

The Client Settings section lets you configure the client's Name and Description. Unlike application-level clients, tenant-level M2M clients don't have Redirect URIs or an Advanced Settings section, since they don't have a login flow.

Configuring JWT Settings

To configure how long access tokens issued to this client remain valid, scroll down to the "JWT Settings" section. Since M2M clients don't use ID tokens or refresh tokens, only Access Token Expiration is configurable here.

Assigning Roles to a Client

A tenant-level M2M client only needs a role if it's calling a Wristband API directly. If the client is only used to authenticate your customer's system against your own application's API, it doesn't need any Wristband permissions at all.

If the client does call a Wristband API directly, assign it a role with the required permissions, scoped with the Tenant boundary so the token can only act within that one tenant.

Permissions and permission boundaries can only be defined at the Application level. Custom roles, however, can be created at either the Application or Tenant level, and a tenant-level client can be assigned roles from both levels.

To assign roles to the tenant-level 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 the client's secret yourself from the dashboard, scroll down to the "Client Secret Settings" section and click the "Rotate" button next to the Primary Client Secret.

After confirming, you'll be shown the new client secret. Record it securely, since it won't be shown again.

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.

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

Deleting a secondary secret can't be undone, and it immediately stops working for authorizing the client.

---

Deleting the 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 this tenant from being able to authenticate with it.

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 your customer from being able to authenticate with it.

---

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.