Skip to content

Authentication

This guide explains how to use authentication with CounterAPI to secure your counters and access private features.

Overview

CounterAPI offers authentication to:

  • Secure your counters from unauthorized access
  • Enable access to private counters
  • Unlock additional features and higher rate limits
  • Track usage across multiple applications with a single account

Note: Authentication is required for the V2 API, which is now the only available CounterAPI version. The legacy V1 API did not support authentication and was deprecated on August 7, 2026.

Registration Process

To use authentication with CounterAPI:

  1. Create an account at counterapi.dev
  2. Click on the "Sign Up" button in the top right corner
  3. Complete the registration form with your email and password

  4. Verify your email address

  5. Create a workspace

  6. After logging in, navigate to the Dashboard
  7. Click "Create Workspace" and provide a name for your workspace

  8. This workspace name will be used in your API clients

  9. Generate an access token

  10. From your Dashboard, navigate to "API Tokens"
  11. Click "Create New Token"
  12. Provide a name for your token (e.g., "Production App", "Development Environment")
  13. Select the appropriate permissions for this token

  14. Click "Generate Token"

  15. Securely store your token

  16. Copy the generated token and store it securely
  17. Important: This token will only be displayed once for security reasons
  18. If you lose your token, you'll need to generate a new one

Using Authentication in Your Applications

Once you have your access token, you can use it with the CounterAPI client libraries. For language-specific implementation details and code examples, refer to:

Security Best Practices

When using authentication tokens, follow these security best practices:

  1. Never hardcode tokens in client-side code
  2. Tokens visible in browser-side code can be extracted by users

  3. For browser applications, consider using a proxy server to make authenticated requests

  4. Use environment variables for server-side applications

  5. Store your tokens in environment variables and access them in your code

  6. Never commit tokens to version control systems

  7. Create multiple tokens with different scopes

  8. Use different tokens for different applications or environments

  9. This allows you to revoke specific tokens if needed without affecting other applications

  10. Rotate tokens periodically

  11. Regularly generate new tokens and phase out old ones

  12. This limits the impact if a token is accidentally exposed

  13. Monitor token usage

  14. Regularly check your CounterAPI dashboard for unusual activity
  15. Set up alerts for unexpected spikes in usage

Token Permissions and Scopes

When creating tokens on counterapi.dev, you can assign specific permissions:

Permission Description
Read Allows retrieving counter values and statistics
Write Allows modifying counter values (increment, decrement, reset)
Admin Allows creating and deleting counters in your workspace

Choose the minimum permissions necessary for each application or environment.

Troubleshooting Authentication

If you encounter authentication issues:

  1. Verify your token is correct
  2. Check for typos or formatting issues

  3. Ensure you're not using a revoked or expired token

  4. Confirm your workspace name

  5. The workspace name is case-sensitive

  6. Make sure it matches exactly what's shown in your CounterAPI dashboard

  7. Check for network issues

  8. Authentication failures can sometimes be caused by network problems

  9. Implement proper error handling to distinguish between authentication errors and network issues

  10. Common error messages

  11. 401 Unauthorized: Invalid or expired token
  12. 403 Forbidden: Token doesn't have required permissions
  13. 404 Not Found: The workspace name is incorrect

If problems persist, contact CounterAPI support through your dashboard.