User Deprovisioning

POST /api/v1/auth/token HTTP/1.1
Host: yourapp.com
Content-Type: application/json
 
{
  "clientId": "abc123",
  "clientSecret": "def456"
}

HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 1800
}

async function handleTokenRequest(clientId: string, clientSecret: string) {
  const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
 
  const response = await fetch(`https://${process.env.APPLICATION_VANITY_DOMAIN}/api/v1/oauth2/token`, {
    method: 'POST',
    headers: {
      Authorization: `Basic ${credentials}`,
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: 'grant_type=client_credentials',
  });
 
  if (!response.ok) {
    throw new Error(`Failed to get token: ${response.status}`);
  }
 
  const { access_token, expires_in } = await response.json();
  return { accessToken: access_token, expiresIn: expires_in };
}

POST /api/v1/users/deprovision HTTP/1.1
Host: yourapp.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
 
{
  "email": "[email protected]"
}

HTTP/1.1 204 No Content

{
  "sub": "sqi7mel4prbixj62rlruslyi64",
  "tnt_id": "ffioj5rc3bd6rnwr7jxhvycfoa",
  "van_dom": "invotastic-demo-wristband.us.wristband.dev",
  "iss": "https://invotastic-demo-wristband.us.wristband.dev",
  "sub_kind": "tenant_client",
  "exp": 1785197092,
  "app_id": "vl6jdobxy5gafkr3dvztbvzrue",
  "iat": 1785110692,
  "jti": "5hbgvgrlejglplvwokwttvazha",
  "client_id": "sqi7mel4prbixj62rlruslyi64"
}

import { createWristbandJwtValidator } from '@wristband/typescript-jwt';
 
// Create once and reuse across requests.
const wristbandJwtValidator = createWristbandJwtValidator({
  wristbandApplicationVanityDomain: process.env.APPLICATION_VANITY_DOMAIN!,
});
 
async function validateCustomerRequest(authorizationHeader: string): Promise<string> {
  // Pull the raw Bearer token out of the Authorization header.
  const token = wristbandJwtValidator.extractBearerToken(authorizationHeader);
 
  // Verify the token's signature, issuer, and expiration.
  const result = await wristbandJwtValidator.validate(token);
 
  if (!result.isValid) {
    throw new Error(`Invalid token: ${result.errorMessage}`);
  }
 
  // A valid signature means this tnt_id can be trusted as the calling customer's tenant.
  const tenantId = result.payload?.tnt_id;
  if (!tenantId) {
    throw new Error('Token is missing a tenant ID');
  }
 
  return tenantId;
}

import { createWristbandM2MClient } from '@wristband/typescript-m2m-auth';
 
const wristbandM2MClient = createWristbandM2MClient({
  clientId: process.env.APPLICATION_CLIENT_ID!,
  clientSecret: process.env.APPLICATION_CLIENT_SECRET!,
  wristbandApplicationVanityDomain: process.env.APPLICATION_VANITY_DOMAIN!,
});
 
const accessToken = await wristbandM2MClient.getToken();

async function findUserIdByEmail(tenantId: string, email: string, accessToken: string): Promise<string> {
  const query = encodeURIComponent(`email eq '${email}'`);
  const response = await fetch(
    `https://${process.env.APPLICATION_VANITY_DOMAIN}/api/v1/tenants/${tenantId}/users?query=${query}`,
    {
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    }
  );
 
  if (!response.ok) {
    throw new Error(`Failed to query user: ${response.status}`);
  }
 
  const { items } = await response.json();
  if (items.length === 0) {
    throw new Error('No matching user found');
  }
 
  return items[0].id;
}

async function findUserIdByExternalId(tenantId: string, externalId: string, accessToken: string): Promise<string> {
  const query = encodeURIComponent(`externalId eq '${externalId}'`);
  const response = await fetch(
    `https://${process.env.APPLICATION_VANITY_DOMAIN}/api/v1/tenants/${tenantId}/users?query=${query}`,
    {
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    }
  );
 
  if (!response.ok) {
    throw new Error(`Failed to query user: ${response.status}`);
  }
 
  const { items } = await response.json();
  if (items.length === 0) {
    throw new Error('No matching user found');
  }
 
  return items[0].id;
}

async function deactivateUser(userId: string, accessToken: string) {
  const response = await fetch(`https://${process.env.APPLICATION_VANITY_DOMAIN}/api/v1/users/$USERID`, {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ status: 'INACTIVE' }),
  });
 
  if (!response.ok) {
    throw new Error(`Failed to deactivate user: ${response.status}`);
  }
}

async function deleteUser(userId: string, accessToken: string) {
  const response = await fetch(`https://${process.env.APPLICATION_VANITY_DOMAIN}/api/v1/users/$USERID`, {
    method: 'DELETE',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
 
  if (!response.ok) {
    throw new Error(`Failed to delete user: ${response.status}`);
  }
}

import { createWristbandM2MClient } from '@wristband/typescript-m2m-auth';
import { createWristbandJwtValidator } from '@wristband/typescript-jwt';
 
const VANITY_DOMAIN = process.env.APPLICATION_VANITY_DOMAIN!;
 
// M2M client used to authenticate the wrapper API's own calls to Wristband.
const wristbandM2MClient = createWristbandM2MClient({
  clientId: process.env.APPLICATION_CLIENT_ID!,
  clientSecret: process.env.APPLICATION_CLIENT_SECRET!,
  wristbandApplicationVanityDomain: VANITY_DOMAIN,
});
 
// JWT validator used to validate the customer's incoming access tokens.
const wristbandJwtValidator = createWristbandJwtValidator({
  wristbandApplicationVanityDomain: VANITY_DOMAIN,
});
 
// Validates a customer's incoming request and returns the tenant it belongs to.
async function validateCustomerRequest(authorizationHeader: string): Promise<string> {
  const token = wristbandJwtValidator.extractBearerToken(authorizationHeader);
  const result = await wristbandJwtValidator.validate(token);
 
  if (!result.isValid) {
    throw new Error(`Invalid token: ${result.errorMessage}`);
  }
 
  const tenantId = result.payload?.tnt_id;
  if (!tenantId) {
    throw new Error('Token is missing a tenant ID');
  }
 
  return tenantId;
}
 
// Resolves a Wristband userId from either an email or an externalId.
async function findUserId(
  tenantId: string,
  email: string | undefined,
  externalId: string | undefined,
  accessToken: string
): Promise<string> {
  const filter = email ? `email eq '${email}'` : `externalId eq '${externalId}'`;
  const query = encodeURIComponent(filter);
  const response = await fetch(
    `https://${VANITY_DOMAIN}/api/v1/tenants/${tenantId}/users?query=${query}`,
    { headers: { Authorization: `Bearer ${accessToken}` } }
  );
 
  if (!response.ok) {
    throw new Error(`Failed to query user: ${response.status}`);
  }
 
  const { items } = await response.json();
  if (items.length === 0) {
    throw new Error('No matching user found');
  }
 
  return items[0].id;
}
 
// Deactivates a user identified by email or externalId.
export async function deactivateUserByEmailOrExternalId(
  authorizationHeader: string,
  email: string | undefined,
  externalId: string | undefined
) {
  if ((!email && !externalId) || (email && externalId)) {
    throw new Error('Provide exactly one of email or externalId');
  }
 
  const tenantId = await validateCustomerRequest(authorizationHeader);
  const accessToken = await wristbandM2MClient.getToken();
  const userId = await findUserId(tenantId, email, externalId, accessToken);
 
  const response = await fetch(`https://${VANITY_DOMAIN}/api/v1/users/$USERID`, {
    method: 'PATCH',
    headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ status: 'INACTIVE' }),
  });
 
  if (!response.ok) {
    throw new Error(`Failed to deactivate user: ${response.status}`);
  }
}

import { createWristbandM2MClient } from '@wristband/typescript-m2m-auth';
import { createWristbandJwtValidator } from '@wristband/typescript-jwt';
 
const VANITY_DOMAIN = process.env.APPLICATION_VANITY_DOMAIN!;
 
// M2M client used to authenticate the wrapper API's own calls to Wristband.
const wristbandM2MClient = createWristbandM2MClient({
  clientId: process.env.APPLICATION_CLIENT_ID!,
  clientSecret: process.env.APPLICATION_CLIENT_SECRET!,
  wristbandApplicationVanityDomain: VANITY_DOMAIN,
});
 
// JWT validator used to validate the customer's incoming access tokens.
const wristbandJwtValidator = createWristbandJwtValidator({
  wristbandApplicationVanityDomain: VANITY_DOMAIN,
});
 
// Validates a customer's incoming request and returns the tenant it belongs to.
async function validateCustomerRequest(authorizationHeader: string): Promise<string> {
  const token = wristbandJwtValidator.extractBearerToken(authorizationHeader);
  const result = await wristbandJwtValidator.validate(token);
 
  if (!result.isValid) {
    throw new Error(`Invalid token: ${result.errorMessage}`);
  }
 
  const tenantId = result.payload?.tnt_id;
  if (!tenantId) {
    throw new Error('Token is missing a tenant ID');
  }
 
  return tenantId;
}
 
// Resolves a Wristband userId from either an email or an externalId.
async function findUserId(
  tenantId: string,
  email: string | undefined,
  externalId: string | undefined,
  accessToken: string
): Promise<string> {
  const filter = email ? `email eq '${email}'` : `externalId eq '${externalId}'`;
  const query = encodeURIComponent(filter);
  const response = await fetch(
    `https://${VANITY_DOMAIN}/api/v1/tenants/${tenantId}/users?query=${query}`,
    { headers: { Authorization: `Bearer ${accessToken}` } }
  );
 
  if (!response.ok) {
    throw new Error(`Failed to query user: ${response.status}`);
  }
 
  const { items } = await response.json();
  if (items.length === 0) {
    throw new Error('No matching user found');
  }
 
  return items[0].id;
}
 
// Deletes a user identified by email or externalId.
export async function deleteUserByEmailOrExternalId(
  authorizationHeader: string,
  email: string | undefined,
  externalId: string | undefined
) {
  if ((!email && !externalId) || (email && externalId)) {
    throw new Error('Provide exactly one of email or externalId');
  }
 
  const tenantId = await validateCustomerRequest(authorizationHeader);
  const accessToken = await wristbandM2MClient.getToken();
  const userId = await findUserId(tenantId, email, externalId, accessToken);
 
  const response = await fetch(`https://${VANITY_DOMAIN}/api/v1/users/$USERID`, {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${accessToken}` },
  });
 
  if (!response.ok) {
    throw new Error(`Failed to delete user: ${response.status}`);
  }
}

POST /api/v1/auth/rotate-secret HTTP/1.1
Host: yourapp.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "clientSecret": "new-secret-value..."
}

import { createWristbandM2MClient } from '@wristband/typescript-m2m-auth';
import { createWristbandJwtValidator } from '@wristband/typescript-jwt';
 
const VANITY_DOMAIN = process.env.APPLICATION_VANITY_DOMAIN!;
 
const wristbandM2MClient = createWristbandM2MClient({
  clientId: process.env.APPLICATION_CLIENT_ID!,
  clientSecret: process.env.APPLICATION_CLIENT_SECRET!,
  wristbandApplicationVanityDomain: VANITY_DOMAIN,
});
 
const wristbandJwtValidator = createWristbandJwtValidator({
  wristbandApplicationVanityDomain: VANITY_DOMAIN,
});
 
// NOTE: This is the part that could be split out into its own endpoint,
// called separately once your customer has deployed and confirmed the
// new secret. See the callout above.
async function deleteSecondarySecret(customerClientId: string, accessToken: string) {
  const response = await fetch(`https://${VANITY_DOMAIN}/api/v1/clients/${customerClientId}/secondary-secret`, {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${accessToken}` },
  });
 
  if (!response.ok) {
    throw new Error(`Failed to delete secondary secret: ${response.status}`);
  }
}
 
export async function rotateCustomerClientSecret(authorizationHeader: string): Promise<string> {
  const token = wristbandJwtValidator.extractBearerToken(authorizationHeader);
  const result = await wristbandJwtValidator.validate(token);
 
  if (!result.isValid) {
    throw new Error(`Invalid token: ${result.errorMessage}`);
  }
 
  // The client_id claim identifies exactly which client this token was issued to.
  const customerClientId = result.payload?.client_id;
  if (!customerClientId) {
    throw new Error('Token is missing a client ID');
  }
 
  const accessToken = await wristbandM2MClient.getToken();
 
  const rotateResponse = await fetch(`https://${VANITY_DOMAIN}/api/v1/clients/${customerClientId}/rotate-secret`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${accessToken}` },
  });
 
  if (!rotateResponse.ok) {
    throw new Error(`Failed to rotate secret: ${rotateResponse.status}`);
  }
 
  const { clientSecret } = await rotateResponse.json();
 
  // Delete the old secondary immediately, so the customer only calls one endpoint.
  await deleteSecondarySecret(customerClientId, accessToken);
 
  return clientSecret;
}