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:
- Sign in to the ToughClicks Management Portal
- Navigate to the Clients tab
- 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
- Click Create Client in the clients page
- Enter a descriptive name (e.g., "Production Web App", "Staging Environment")
- Optionally configure domain restrictions
- Click Save
You'll receive a Client ID (token) that looks like: cli_abc123def456
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
- Open the client details page
- Navigate to Domain Restrictions
- Click Add Domain
- Enter the domain (e.g.,
example.com,app.example.com) - 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
| Configuration | Allows | Blocks |
|---|---|---|
example.com | https://example.com | https://app.example.com |
example.comapp.example.com | https://example.comhttps://app.example.com | https://staging.example.com |
| No restrictions | Any domain | None |
Localhost and Development
For local development, add localhost domains:
localhostlocalhost:3000(with port if needed)127.0.0.1
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
- Open client details
- Click the remove icon next to the domain
- Confirm removal
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
- Open the client details page
- Find the Expiration Date section
- Select a date and time
- Click Save
Once the expiration date passes, the client will stop working immediately.
Removing an Expiration
- Open client details
- Clear the expiration date field
- Click Save
The client will be active again with no expiration.
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:
-
Different Environments
- Production Web Client
- Staging Web Client
- Development Web Client -
Different Applications
- Web Application Client
- Mobile App Client
- Admin Portal Client -
Different Regions
- US Production Client
- EU Production Client
- APAC Production Client
Security Best Practices
- Use Domain Restrictions in Production: Always configure allowed domains for production clients
- Separate Environments: Never use the same client for development and production
- Regular Audits: Periodically review active clients and expire unused ones
- Rotate When Compromised: If a client is exposed, expire it and create a new one
- 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
- Create new client with appropriate configuration
- Update your application to use the new Client ID
- Deploy the updated application
- Monitor to ensure the new client works correctly
- Expire the old client after migration is complete
Handling a Security Breach
- Immediately set an expiration date on the compromised client
- Create a new replacement client with domain restrictions
- Update your application with the new Client ID
- Deploy as quickly as possible
- 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