User Data

Set up username and email in authentication tokens for the embedded board

User Data

The embedded board receives user information (name, email, avatar) from the JWT token you generate. This data is used to display the user's identity in feedback submissions, comments, and votes.

How User Data Flows

Your Application: User is logged into your application
Token Endpoint: Your endpoint generates a JWT with required user data (name, email) in the token claims
Round Two: Verifies the token, validates required claims, and extracts user information
Embedded Board: Displays user name, email, and avatar throughout the interface

Important: The name and email claims are required. Tokens without these claims will be rejected during verification.

Required Token Claims

Include these claims in your JWT token to provide user data:

Required Claims

sub: Your application's unique user ID (required)
name: User's display name (required) - Must be a non-empty string
email: User's email address (required) - Must be a valid email address format

Optional Claims

avatar_url: URL to user's avatar image (optional)

Example Token Payload

{
  "iss": "yourworkspace/yourboard",
  "aud": "roundtwo",
  "sub": "user-12345",
  "name": "John Doe",
  "email": "john@example.com",
  "avatar_url": "https://example.com/avatars/john.jpg",
  "exp": 1234567890,
  "iat": 1234567890
}

Important: The iss (issuer) claim must be in the format "[workspace]/[board]" in lowercase, exactly as shown in your Round Two embed settings. For example, if your workspace is "My Workspace" and your board is "Product Feedback", the issuer should be "my workspace/product feedback" (all lowercase).

Implementation Examples

app.post('/api/roundtwo/token', authenticateUser, async (req, res) => {
  try {
    const user = req.user; // Your authenticated user
    
    const payload = {
      iss: 'yourworkspace/yourboard',
      aud: 'roundtwo',
      sub: user.id, // Required: unique user ID
      name: user.name || user.displayName, // Required: display name (non-empty string)
      email: user.email, // Required: email address (valid format)
      avatar_url: user.avatarUrl || user.profilePicture, // Optional: avatar URL
      exp: Math.floor(Date.now() / 1000) + 300,
      iat: Math.floor(Date.now() / 1000),
    };
    
    const token = jwt.sign(payload, privateKey, { algorithm: 'RS256' });
    res.json({ token });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});

@app.route('/api/roundtwo/token', methods=['POST'])
@require_auth
def generate_token(user):
    payload = {
        'iss': 'yourworkspace/yourboard',  # Format: "[workspace]/[board]" in lowercase
        'aud': 'roundtwo',
        'sub': user.id,  # Required: unique user ID
        'name': user.name,  # Required: display name (non-empty string)
        'email': user.email,  # Required: email address (valid format)
        'avatar_url': user.avatar_url,  # Optional: avatar URL
        'exp': int(time.time()) + 300,
        'iat': int(time.time()),
    }
    
    token = jwt.encode(payload, private_key, algorithm='RS256')
    return jsonify({'token': token})

Where User Data Appears

User data from your token is displayed throughout the embedded board:

Feedback Submissions: Author name and avatar shown on feedback items
Comments: Author name and avatar shown on comments
Votes: User's vote status tracked and displayed
User Profile: Name and email used for identity matching if user later signs up for Round Two
Feedback Attribution: All feedback, votes, and comments are attributed to the user based on the sub claim

How User Data Flows to the Embedded Board

Your Token Endpoint: Includes name, email, and avatar_url in the JWT token claims
Round Two Verification: Extracts user data from token claims during verification at /api/embed/auth/verify
External User Creation: Creates or updates an external user record with the provided data
Embedded Board: Receives user data via the embed session and displays it throughout the interface

The embedded board automatically receives and displays this information - no additional configuration needed in Round Two. Simply ensure your token includes the required claims (name, email) and optional avatar_url claim.

Configuration in Your Token Endpoint

To ensure user data is passed to the embedded board, include these claims when generating your JWT token:

const payload = {
  iss: 'yourworkspace/yourboard',
  aud: 'roundtwo',
  sub: user.id, // Required: unique user ID
  name: user.name || user.displayName, // Include for display name
  email: user.email, // Include for email (enables identity matching)
  avatar_url: user.avatarUrl || user.profilePicture, // Include for avatar
  exp: Math.floor(Date.now() / 1000) + 300,
  iat: Math.floor(Date.now() / 1000),
};

Important Notes:

The name claim is required and must be a non-empty string. It's used to display the user's name on feedback items and comments.
The email claim is required and must be a valid email address format. It's used for identity matching if the user later signs up for Round Two.
The avatar_url claim is optional but recommended. It should be a publicly accessible HTTPS URL to the user's avatar image.
Tokens without name or email will be rejected during verification.

Identity Matching

If a user who has submitted feedback via the embed later signs up for Round Two directly, their identity is automatically linked using the email address:

User submits feedback via embed with email user@example.com
User later signs up for Round Two with the same email
Round Two automatically links their embedded feedback to their Round Two account
All feedback, votes, and comments are unified under one identity

Important: Including the email claim in your tokens enables this identity matching. If you don't include email, users will need to manually link their accounts.

Best Practices

Always Include Email: Enables automatic identity matching
Use Consistent User IDs: The sub claim should be stable and unique per user
Provide Display Names: Makes feedback more personal and identifiable
Include Avatar URLs: Improves visual recognition in feedback lists
Keep Data Current: Update user information if it changes in your system

Troubleshooting

User Name Not Displaying

Verify name claim is included in token
Check that token is being generated correctly
Ensure user data is available in your authentication system

Email Not Matching

Verify email claim matches exactly (case-sensitive)
Check that email is included in token payload
Ensure email format is valid

Avatar Not Showing

Verify avatar_url is a valid, accessible URL
Check that URL returns an image (not 404)
Ensure URL uses HTTPS for security

Next Steps

Testing - Verify user data displays correctly
Security - Learn about securing your integration

Token Endpoint

Testing