Token Invalidation

Overview

This API provides a secure mechanism to invalidate JWT tokens using a token versioning system. When you invalidate a token, all existing tokens for that user become invalid immediately.

How It Works

Token Versioning System

Each customer_user has a token_version field that starts at 0. When a JWT token is generated, it includes the current token_version in its payload:

{
  "sub": "customer-user-id",
  "tokenVersion": 0,
  "companyId": "company-id",
  "agentId": "agent-id",
  ...
}

When you invalidate tokens, the system increments the token_version in the database. All tokens with the old version become invalid immediately.

Endpoint

POST https://api.perform.chat/rest/v1/auth/invalidate-token

Request Body

{
  "keyId": "your-api-key-id",
  "keySecret": "your-api-key-secret",
  "customerUserId": "customer-user-id-to-invalidate"
}

Parameters

Note: The customerUserId is the user.id returned when you generate a token. See Token Generation for details.

Response

Success (200)

{
  "message": "All tokens invalidated successfully",
  "customerUserId": "customer-user-123",
  "newTokenVersion": 1
}

Error Responses

401 Unauthorized - Invalid API Credentials

{
  "statusCode": 401,
  "message": "Invalid API credentials"
}

400 Bad Request - Customer User Not Found

{
  "statusCode": 400,
  "message": "Customer user not found or does not belong to your company"
}

Token Validation Flow

When a request is made with a JWT token:

1. Check if JWT signature is valid
2. Check if JWT has not expired (expiresIn)
3. Check if customer_user exists and is active
4. Check if token version matches (payload.tokenVersion === customer_user.token_version)
5. Check if user belongs to the correct company
6. Check if agent is active

If any check fails, the request is rejected with 401 Unauthorized.

Workflow Diagram

Token Expiration vs Invalidation

Both methods work together:

• Tokens expire automatically after expiresIn period
• Tokens can be manually invalidated at any time
• After invalidation, users must generate a new token via POST /rest/v1/auth/token

Security Features

1. API Key Authentication Required

You must provide valid keyId and keySecret to invalidate tokens. This prevents attackers from invalidating tokens even if they intercept a JWT.

2. Company Isolation

The system verifies that the customer_user belongs to the same company as your API Key. You cannot invalidate tokens for users outside your company.

3. Immediate Invalidation

Token invalidation is immediate. All existing tokens become invalid on the next request.

Best Practices

1. Store API credentials securely - Never expose keySecret in client-side code
2. Invalidate on security events - Always invalidate tokens after password resets, permission changes, or suspicious activity
3. Store customer user IDs - Save the customerUser.id from token generation for future invalidation

Related Endpoints

• Token Generation - Generate a new JWT token
• Customer Users - Learn about customer user management