Impossible to create a Guest user - Documentation vs SDK behavior mismatch

[lparrouy]

Description

There's a critical discrepancy between the documentation and the actual SDK behavior when trying to initialize the SDK with a UserType.Guest.

Context

I'm trying to initialize the GetStream Video SDK on Android with a guest user that has a custom user_id generated by my backend (not !anon). The same backend works perfectly on iOS, but on Android I'm getting a 401 error:
CreateGuest failed with error: "anon auth token must have user_id claim equal to '!anon'"

The Documentation Says

According to the official documentation, you can initialize a guest user like this:

val streamVideo = StreamVideoBuilder(
    context = context,    
    apiKey = apiKey,    
    geo = GEO.GlobalEdgeNetwork,    
    user = User(
        id = "guest", 
        type = UserType.Guest
    )
).build()

No token is mentioned in the documentation for guest users.

The SDK Reality

However, when trying this approach:

1. The SDK requires a token - Without providing a token, initialization fails with "token cannot be empty"
2. If you provide a token with a custom user_id (generated by our backend), you get:
   CreateGuest failed with error: "anon auth token must have user_id claim equal to '!anon'"
3. Looking at the SDK source code, I found this behavior in the SDK:

if (user.type == UserType.Guest) {
    coordinatorConnectionModule.updateAuthType("anonymous")
    client.setupGuestUser(user)
} else if (user.type == UserType.Anonymous) {
    coordinatorConnectionModule.updateAuthType("anonymous")
}

fun setupGuestUser(user: User) {
    guestUserJob = scope.async {
        val response = createGuestUser(
            userRequest = UserRequest(
                id = user.id,
                image = user.image,
                name = user.name,
                custom = user.custom,
            ),
        )
        if (response.isFailure) {
            throw IllegalStateException("Failed to create guest user")
        }
        response.onSuccess {
            coordinatorConnectionModule.updateAuthType("jwt")
            coordinatorConnectionModule.updateToken(it.accessToken)
        }
    }
}

The SDK is trying to call createGuestUser() automatically, which requires the user to have !anon as the user_id.

The Problem

There's a fundamental confusion about guest users:

• UserType.Anonymous: Requires user_id = "!anon" but you can provide your own token
• UserType.Guest: SDK creates the guest automatically via GetStream API, ignoring any token you provide
• UserType.Authenticated: Works with custom tokens but doesn't semantically represent a "guest"

Use Case

We need guest users with:
✅ Custom user_id (managed by our backend, not !anon)
✅ Custom JWT tokens (generated by our backend)
✅ Limited access to specific calls via call_cids in the JWT
✅ Cross-platform consistency (same backend works on iOS)

Steps to Reproduce

// Our backend generates a JWT token with:
// {
//   "user_id": "custom-guest-uuid-123",
//   "role": "guest",
//   "call_cids": ["default:call-id"],
//   "iat": ...,
//   "exp": ...
// }

val guestToken = myBackend.getGuestToken()

// Attempt 1: Following documentation (no token)
val streamVideo = StreamVideoBuilder(
    context = context,
    apiKey = apiKey,
    geo = GEO.GlobalEdgeNetwork,
    user = User(id = "custom-guest-uuid-123", type = UserType.Guest)
).build() // ❌ Fails: token cannot be empty

// Attempt 2: Providing our custom token
val streamVideo = StreamVideoBuilder(
    context = context,
    apiKey = apiKey,
    geo = GEO.GlobalEdgeNetwork,
    user = User(id = "custom-guest-uuid-123", type = UserType.Guest),
    token = guestToken
).build() // ❌ Fails: "anon auth token must have user_id claim equal to '!anon'"

Expected Behavior

Either:

1. The documentation should clearly explain that UserType.Guest doesn't support custom tokens and will auto-create guests via GetStream API with !anon user_id
   Or:
2. UserType.Guest should support custom JWT tokens with custom user_id (like iOS seems to do)

Actual Behavior

• Documentation suggests guest users can be created without tokens
• SDK requires a token
• SDK only accepts tokens with user_id = "!anon" for guests

Environment

• SDK Version: 1.17
• Android Version: Android 16
• Device: Google Pixel 9a

Thank you for your help.