User Identity

Overview

The SDK supports two layers of identity:

Layer	How It Works	Scope
Device ID	Automatic — generated on first use	Conversations scoped to the device
User Identity	Opt-in — set a JWT token via `identify()`	Conversations scoped to the user

The SDK works anonymously out of the box. Call identify() to associate conversations with a specific user.

Device ID

Every SDK instance has a stable device ID, generated automatically on creation:

val deviceId: String

val client = Chatbase.create(context, "YOUR_AGENT_ID")
println(client.deviceId) // "a1b2c3d4-e5f6-..."

The device ID uses Android’s Settings.Secure.ANDROID_ID when available. On emulators or when restricted, it falls back to a UUID persisted in SharedPreferences (chatbase_sdk_prefs). The ID remains stable across app launches.

identify

interface ChatbaseClient — Package: com.chatbase.sdk

suspend fun identify(token: String)

Verify a JWT token with the Chatbase server and identify the current user. Subsequent requests are associated with this user. identify() is equivalent to verify() — it verifies the token server-side and triggers the anonymous-conversation merge.

String

required

A JWT generated by your backend and signed with your agent’s identity verification secret. The payload must include a user_id (or sub) claim.

Generate a JWT on your backend

Create a signed JWT token on your server containing the user ID in its payload.

Pass the token to the SDK

client.identify(jwtToken)

Conversations are now scoped to this user.

Check identity status

println(client.isIdentified)   // true
println(client.currentUserId)  // "user_123" (confirmed by the server during verification)

Identity Properties

val deviceId: String

Auto-generated device ID. Always available.

val isIdentified: Boolean

true if a JWT token has been set via identify().

val currentUserId: String?

User ID confirmed by the server when the token was verified. null if not identified.

verify

suspend fun verify(token: String)

Verify a JWT token with the Chatbase server. On success, the server also merges any conversations created anonymously (with the device ID) into the verified user’s account. identify() is an alias for this method.

String

required

The JWT token to verify.

try {
    client.verify(jwtToken)
    println("Token is valid")
} catch (e: ApiException) {
    println("Token verification failed: ${e.errorMessage}")
}

When verify() succeeds, the server automatically merges previously anonymous (device-scoped) conversations into the verified user’s account. Conversations started before identification are preserved and accessible under the user’s identity.The merge runs asynchronously on the server — a listConversations() call issued immediately after verify() returns may not reflect it yet.

How Identity Affects Conversations

When identified, conversations are scoped to the user — listConversations() returns only that user’s conversations. Without identity, conversations are scoped to the device.

logout

fun logout()

Clear the JWT token and return to anonymous (device-scoped) mode. Also clears the current conversation ID so the next message starts a fresh anonymous conversation.

client.logout()

println(client.isIdentified)          // false
println(client.currentUserId)         // null
println(client.currentConversationId) // null
println(client.deviceId)              // still available — unchanged

identify() and verify() are equivalent — both verify the token with the server and trigger the merge of prior anonymous (device-scoped) conversations into the user’s account. You never need to call both.

Conversations & History

List conversations and load message history

Overview

SDK setup and configuration

Getting Started

Reference

Overview

Device ID

identify

Identity Properties

verify

How Identity Affects Conversations

logout

Conversations & History

Overview

​Overview

​Device ID

​identify

​Identity Properties

​verify

​How Identity Affects Conversations

​logout

​Related

Conversations & History

Overview

Overview

Device ID

identify

Identity Properties

verify

How Identity Affects Conversations

logout

Related