Client (Admin) Tokens vs User Tokens: Understanding API Authentication

In this article, you'll learn the difference between client (admin) tokens from staff profiles and user tokens (from regular accounts) to avoid authentication errors when making API calls. Understanding which token type to use for specific endpoints is essential for successful API integration.

📖 What's the Key Difference Between Client and User Tokens?

Client (Admin) Tokens come from staff profiles that can be created in the Management Portal. These profiles have administrative access with three levels of permissions that one can choose from:

• Client Editor
• Client Product Manager
• Client Admin

User Tokens come from regular user profiles. These allow standard actions like participating in games, using features, and writing comments. However, actions that require elevated authentication cannot be performed with basic user tokens - for example, for certain API endpoint calls, administrative client tokens are required. In such cases, using the wrong token type can cause authentication errors.

📖 When Do You Need Client (Admin) Tokens?

As specified earlier, some API endpoints require elevated permissions and will only work with client (admin) tokens.

Example: The "Get Classic Quizzes participations" endpoint requires a client (admin) token, not a regular user token.

Example: API endpoint requiring a client token

This is just one of many endpoints that require a client token. The "Get Classic Quizzes participations" endpoint shows "Authentication: Personal Bearer token acquired from Firebase with sufficient user permissions" - this means it requires a client token from a staff profile, not a regular user token.

📖 How to Get Client (Admin) Tokens

To create staff profiles for other people (regardless of whether they'll be Client Editor, Client Product Manager, or Client Admin), you must already have a high enough role with sufficient permissions. If you are a 'Client Admin', you can create profiles for other staff members with no issues.

📨 If you believe you need a higher level of permission, you can reach out to our support team for assistance.

Step 1: Create a Staff Profile

1. Log into the Management Portal
2. Go to Staff → Click the blue Create button
3. Fill in the details and select a role (hover over the '?' buttons to see detailed info about what each role gives access to):
   • Client Editor
   • Client Product Manager
   • Client Admin
4. Click Create

Step 2: How Can Staff Members Get Their Own Client Tokens?

1. Log in using the staff profile credentials
2. Obtain the token for this profile
3. Use this token for API requests that require client (admin) tokens

📖 Important: "Staff (Admin) Profile" vs "User Profile Marked as Staff"

Don't confuse these two different concepts:

Staff (Admin) Profile = A profile created through the Management Portal with access level of either Client Editor, Client Product Manager, or Client Admin. One can get one's client token with admin permissions and perform multiple API calls.

Regular User Marked as Staff = These are regular end user accounts, marked as 'staff'. Regular end user accounts do not have administrative rights levels (e.g., Client Editor, Client Product Manager), unlike staff profiles.

If one gets one's own token, this is a simple USER token, and NOT an admin (client) token. One can participate in games, comment, etc., however, one cannot perform API calls requiring client (admin) tokens.

Regular Users Marked as Staff

Regular user profiles can be marked as "staff" through the user management interface. However, this doesn't change their token type - it's still just a user token without any administrative rights.

How to mark a regular user as staff:

1. Go to Profiles in the Management Portal
2. Find the user and click the Actions menu (three dots)
3. Select "Mark profile as staff member"
4. Confirm the action

Once confirmed, a distinct icon will appear next to the user's nickname to visually show the profile has been marked as 'staff'.

Why mark users as staff? This is useful when platform staff participate in platform games for testing purposes. Marking them as "staff" allows you to exclude their scores from leaderboards so only real users appear in rankings. This is just one example of a use case - platforms can decide to mark their workers as 'staff' for various reasons and applications.

Key point: A regular user marked as "staff" still has a user token, not a client token with administrative rights.

Common Mistakes

❌ Wrong: Using a regular user token (even if profile is marked as staff) for endpoints requiring admin tokens
❌ Wrong: Thinking "marked as staff" gives admin API access
✅ Correct: Using a client token from a staff profile with administrative rights created in Management Portal

Troubleshooting

If you get authentication errors:

1. Check if the endpoint requires "sufficient user permissions"
2. Verify you're using a client token (from staff profile)
3. Ensure your staff role has enough permissions
4. Even if you're correctly using a client (admin) token, sometimes you might need to have the role upgraded (e.g., to 'Client Admin') to be able to perform certain actions

Common error response when using wrong token type: (eg. User token when a Client (Admin) token is required instead)

Need help? Contact our support with information about the specific endpoint, token type, and any error messages you're receiving 📨