Skip to main content
Version: Isle Royale (2.5.0)

Managing Clients

Clients represent your applications or integrations in the ToughClicks system. Each client has a unique Client ID that authenticates your API requests and controls where your integration can be used.

Accessing Clients​

To manage your clients:

  1. Sign in to the ToughClicks Management Portal
  2. Navigate to the Clients tab
  3. Here you can view, create, and configure all your clients

What is a Client?​

A client is a credential that represents one of your applications or environments in ToughClicks. It serves several purposes:

  • Authentication: Identifies your application when making API requests
  • Security: Controls which domains can use the integration
  • Organization: Separates different environments or applications
  • Access Control: Can be expired or revoked if compromised

Creating a New Client​

  1. Click Create Client in the clients page
  2. Enter a descriptive name (e.g., "Production Web App", "Staging Environment")
  3. Optionally configure domain restrictions
  4. Click Save

You'll receive a Client ID (token) that looks like: cli_abc123def456

Secure Your Client ID

Your Client ID should be treated as a credential. While it's safe to use in client-side code (it's designed for this), you should:

  • Not commit it to public repositories with domain restrictions disabled
  • Use different clients for production vs. development
  • Rotate clients if you suspect compromise

Client ID​

The Client ID is the unique identifier for your client. You'll use this in your integration code.

Finding Your Client ID:

  • Listed in the clients table
  • Visible in the client details page
  • Copy it directly from the portal

Using Your Client ID:

const tc = new ToughClicks({
clientId: 'cli_abc123def456', // Your Client ID
packetId: 'pkt_xyz789'
});

Client Domains​

Client domains provide an additional layer of security by restricting which domains can use your Client ID.

How Domain Restrictions Work​

ToughClicks validates requests by checking the HTTP Origin header against your configured domain list. If the request comes from an unauthorized domain, it will be rejected.

Configuring Allowed Domains​

  1. Open the client details page
  2. Navigate to Domain Restrictions
  3. Click Add Domain
  4. Enter the domain (e.g., example.com, app.example.com)
  5. Click Save

Domain Format:

  • Use the full domain: app.example.com
  • Do not include protocol: https://app.example.com
  • Do not include paths: example.com/app
  • Subdomains are treated separately: app.example.com ≠ example.com

Examples​

ConfigurationAllowsBlocks
example.comhttps://example.comhttps://app.example.com
example.com
app.example.com
https://example.com
https://app.example.com
https://staging.example.com
No restrictionsAny domainNone

Localhost and Development​

For local development, add localhost domains:

  • localhost
  • localhost:3000 (with port if needed)
  • 127.0.0.1
Development vs Production

Use separate clients for development and production:

  • Development Client: Allow localhost, *.dev.example.com
  • Production Client: Only allow production domains

Wildcard Domains​

Currently, wildcard domains are not supported. You must explicitly list each subdomain:

// You must list each subdomain
app.example.com
api.example.com
staging.example.com

Removing Domain Restrictions​

  1. Open client details
  2. Click the remove icon next to the domain
  3. Confirm removal
Public Clients

A client with no domain restrictions can be used from any domain. Only use this configuration if:

  • You're in development and need flexibility
  • Your application is truly public and doesn't need domain restrictions
  • You understand the security implications

Client Expiration​

Client expiration allows you to set an end date for a client, after which it will no longer work.

When to Use Expiration​

  • Security Breach: Immediately expire a compromised client
  • Deprecated Applications: Phase out old integrations
  • Temporary Access: Grant time-limited access for contractors or specific projects
  • Environment Cleanup: Expire unused sandbox/testing clients

Setting an Expiration Date​

  1. Open the client details page
  2. Find the Expiration Date section
  3. Select a date and time
  4. Click Save

Once the expiration date passes, the client will stop working immediately.

Removing an Expiration​

  1. Open client details
  2. Clear the expiration date field
  3. Click Save

The client will be active again with no expiration.

Immediate Effect

Expiring a client takes effect immediately. Any active integrations using that client will stop working. Make sure you have a replacement client ready if needed.

Client Management Best Practices​

Naming Conventions​

Use descriptive names that indicate:

  • Environment: "Production", "Staging", "Development"
  • Application: "Web App", "Mobile App", "API Integration"
  • Purpose: "User Facing", "Internal Tools", "Partner Integration"

Good Examples:

  • "Production Web Application"
  • "Staging Mobile App"
  • "Development Environment - John's Machine"
  • "Partner Integration - Acme Corp"

Poor Examples:

  • "Client 1"
  • "Test"
  • "New Client"

Multiple Clients Strategy​

Create separate clients for:

  1. Different Environments

    - Production Web Client
    - Staging Web Client
    - Development Web Client
  2. Different Applications

    - Web Application Client
    - Mobile App Client
    - Admin Portal Client
  3. Different Regions

    - US Production Client
    - EU Production Client
    - APAC Production Client

Security Best Practices​

  1. Use Domain Restrictions in Production: Always configure allowed domains for production clients
  2. Separate Environments: Never use the same client for development and production
  3. Regular Audits: Periodically review active clients and expire unused ones
  4. Rotate When Compromised: If a client is exposed, expire it and create a new one
  5. Document Usage: Use descriptions to note where each client is used

Lifecycle Management​

Creating New Clients:

  • Create before you need them
  • Configure domain restrictions immediately
  • Document the purpose in the description

Updating Clients:

  • Update domain lists as your infrastructure changes
  • Keep descriptions current
  • Coordinate changes with deployments

Retiring Clients:

  • Set expiration dates for planned retirement
  • Update integrations to use new clients first
  • Monitor for any remaining usage before final expiration

Common Scenarios​

Migrating to a New Client​

  1. Create new client with appropriate configuration
  2. Update your application to use the new Client ID
  3. Deploy the updated application
  4. Monitor to ensure the new client works correctly
  5. Expire the old client after migration is complete

Handling a Security Breach​

  1. Immediately set an expiration date on the compromised client
  2. Create a new replacement client with domain restrictions
  3. Update your application with the new Client ID
  4. Deploy as quickly as possible
  5. Investigate how the breach occurred

Multi-Region Deployment​

// Different clients per region
const clientConfig = {
'us': 'cli_us_production',
'eu': 'cli_eu_production',
'apac': 'cli_apac_production'
};

const tc = new ToughClicks({
clientId: clientConfig[userRegion],
packetId: 'pkt_global_signup'
});

Development to Production​

// Environment-based client selection
const CLIENT_ID = process.env.NODE_ENV === 'production'
? 'cli_production_12345'
: 'cli_development_67890';

const tc = new ToughClicks({
clientId: CLIENT_ID,
packetId: 'pkt_user_signup'
});

Troubleshooting​

"Invalid Client" Error​

Possible causes:

  • Client has expired - check expiration date
  • Client ID is incorrect - verify you copied it correctly
  • Client has been deleted

Solution: Verify the client exists and is active in the Management Portal

"Domain Not Allowed" Error​

Possible causes:

  • Request is coming from an unauthorized domain
  • Domain restrictions are configured incorrectly
  • Missing protocol-relative domain configuration

Solution:

  • Check the exact domain in your browser's address bar
  • Add that domain to the client's allowed domains list
  • Remember subdomains must be explicitly listed

Client Works Locally but Not in Production​

Likely cause: Domain restrictions

Solution:

  • Ensure production domain is in the allowed domains list
  • Check for subdomain mismatches (www vs non-www)
  • Verify the correct client is being used in production

Sudden "Invalid Client" in Production​

Possible causes:

  • Client expired automatically
  • Someone manually expired the client
  • Domain restrictions were recently modified

Solution:

  • Check client expiration date
  • Review recent changes to the client
  • Verify domain restrictions still match your deployment

Next Steps​