Skip to main content

Terminology

This page defines key concepts and terminology used throughout the UG Labs API and SDK documentation.

API Key​

Credentials used for authenticating with the UG Labs platform to obtain access tokens. There are two types:

  • Private API Key: Used by developers to authenticate and manage resources
  • Public API Key: Used for player authentication and access control

API keys are managed through the UG Labs Console.

Authentication​

The process of verifying an entity's identity and obtaining a matching authentication token. The implementation varies depending on the entity type (developer vs. player).

See the Authentication Guide for detailed information.

Authentication Token​

A piece of information attached to every authenticated API request to identify the session. Authentication tokens are typically used as Bearer tokens in the HTTP Authorization header.

Token Expiration

Authentication tokens expire approximately 60 minutes after issuance. Your application should handle token refresh or re-authentication.

External ID​

A unique identifier assigned by your team to identify players. This can be an email address, phone number, device ID, or any other identifier that is unique within your team.

The UG Labs platform treats external IDs as opaque strings and only requires that they are unique at the team level. This allows you to use your existing user identification system.

Federated ID​

A globally-unique secret identifier provisioned by UG Labs for each player. The federated ID is generated when a player is created and is used for player authentication via public API keys.

Keep Federated IDs Secret

Federated IDs must be kept confidential to prevent unauthorized account access. Never expose federated IDs in client-side code, logs, or public repositories.

Player​

An entity that consumes experiences built on the UG Labs platform. Players are identified by the combination of:

  • External ID (assigned by your team)
  • Team

Each player is provisioned with a unique federated ID for secure authentication.

Session​

A single connection to the UG Labs platform that manages one conversation history thread. Each WebSocket connection represents a session, and sessions maintain context for the duration of the connection.

When a connection is closed, the session ends. To resume a conversation, you can import the session history when creating a new connection.

Team​

A group of users who share access to UG Labs resources and permissions. Teams enable collaboration and resource organization:

  • Resources (players, API keys, configurations) are scoped to teams
  • The same user can belong to multiple teams
  • Teams provide isolation between different projects or environments

User / Service Account​

Development-oriented entities on the UG Labs platform:

Human Users​

  • Associated with email addresses
  • Can authenticate via SSO (Google) or API keys
  • Have full access to team resources

Service Accounts​

  • Programmatic access accounts
  • Authenticate using public API keys
  • Typically used for player-facing applications
  • Have read-only access to specific resources

Additional Concepts​

Utilities​

Functions that extract structured information from conversations. There are two types:

  • Classify: Match user input against predefined answers
  • Extract: Generate text responses based on conversation context

See the Utilities Guide for more information.

Prompt​

A Jinja2-templated system message that defines the AI assistant's behavior and context. Prompts can include dynamic variables that are populated at runtime.

Interruption (Barge-in)​

The ability for users to interrupt the AI assistant while it's speaking, enabling more natural conversations. The platform uses Acoustic Echo Cancellation (AEC) to detect interruptions reliably.

Next Steps​