Tenant-Level Clients
Let your customers authenticate calls to your application's APIs using tenant-level OAuth2 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.
Figure 1. Illustration demonstrating how tenant machines can use tenant-level M2M clients to retrieve access tokens to call your application's APIs.
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.
Figure 2. OAuth2 Clients page in Tenant View showing the M2M Client Name field and 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.
Figure 3. Success dialog displaying the newly created client's Client ID and Client Secret.
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.
Figure 4. OAuth2 Clients table in Tenant View showing a list of clients to select for editing.
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.
Figure 5. Client Settings section on the Edit Client page for a tenant-level M2M client showing Name and Description fields.
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.
Figure 6. JWT Settings section on the Edit Client page for a tenant-level M2M client showing only the Access Token Expiration field.
Assigning Roles to a Client
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.
Figure 7. Roles section on the Edit Client page for a tenant-level M2M client showing the Assigned Roles multi-select dropdown.
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.
Figure 8. Client Secret Settings section on the Edit Client page for a tenant-level M2M client showing the Client Secret field and 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.
Figure 9. Client Secret Settings section on the Edit Client page for a tenant-level M2M client showing the Rotate button for the Primary Client Secret.
After confirming, you'll be shown the new client secret. Record it securely, since it won't be shown again.
Figure 10. Success dialog showing the new client secret after rotation.
Rotating secrets generates a new primary secret in place of the current one. The current secret becomes the secondary client secret, and both remain valid for authenticating 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.
Figure 11. Client Secret Settings section on the Edit Client page for a tenant-level M2M client showing the Delete button for the Secondary Client Secret.
Deleting a secondary secret can't be undone, and it immediately stops working for authenticating 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.
Figure 12. Delete This Client section on the Edit Client page for a tenant-level M2M client with a warning and Delete button.
Scroll to the bottom of the Edit Client page to the "Delete This Client" section, then click the "Delete" button. Once the client is deleted it can no longer be used to issue new access tokens.
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.
Figure 13. Generate Access Tokens section on the Edit Client page for a tenant-level M2M client showing the Client Secret field and New Token button.
You'll be shown the access token. Copy it somewhere safe, since it won't be shown again.
Figure 14. Your Access Token success dialog displaying the generated access token.
Updated 20 days ago