User Identity

Overview

The SDK has two levels of identity:

Level	How it works	What conversations belong to
Device ID	Automatic, created on first use	The device
User identity	Optional, you call `identify(token:)`	The user

The SDK works anonymously out of the box. Call identify(token:) to tie conversations to a specific user. Every request includes the device ID in an X-Device-Id header. Once the user is signed in, requests also include the JWT in X-User-Token. The SDK sets both headers for you.

Device ID

Every install gets a device ID the first time the SDK needs one:

public var deviceId: String { get }

let client = ChatbaseClient(agentId: "YOUR_AGENT_ID")
print(client.deviceId) // "A1B2C3D4-E5F6-..."

The device ID is a UUID saved in UserDefaults.standard under the key com.chatbase.sdk.deviceId. It stays the same across app launches and across clients, and it is created only once per install, even if you create several clients at the same time on a cold start.

Because it lives in UserDefaults, the device ID does not survive a reinstall, and it is included in device backups, so restoring a backup on a new device reuses the same ID. Anonymous conversations follow that ID. If you want conversations to survive a reinstall, sign the user in with a JWT.

identify

public func identify(token: String) async throws

Checks a JWT with the Chatbase server and signs the user in. Later requests belong to that user, and the token is saved so the user stays signed in after the app restarts.

String

required

An HS256 JWT created by your backend and signed with your agent’s identity verification secret. The payload needs a user_id (or sub) claim.

Create a JWT on your backend

Sign a JWT with your agent’s identity verification secret, with the user ID in the payload. See Identity Verification for the token format and where to find the secret.

Never put the identity verification secret in your app. Anyone can pull it out of an app bundle. Create tokens on your server and fetch them through your own API.

Pass the token to the SDK

do {
    try await client.identify(token: jwt)
} catch {
    // The token was rejected. See Error Handling.
}

Conversations now belong to this user.

Check that it worked

if case .identified = client.authState {
    print("Signed in")
}
print(client.currentUserId)  // set after the first reply finishes

identify(token:) throws if the token is invalid, expired, signed with the wrong secret, or if identity verification is not set up for the agent. When it throws, the SDK’s sign-in state does not change, so a failed call cannot leave you half signed in.

When sign-in succeeds, the server also moves conversations created anonymously on this device into the user’s account, so history from before sign-in is kept.The server does this in the background. A listConversations() call made right after identify returns may not show them yet. Refresh a moment later, or the next time the screen appears.

AuthState

public enum AuthState: Sendable, Equatable {
    case anonymous
    case identified(token: String)
}

public var authState: AuthState { get }

switch client.authState {
case .anonymous:
    showSignInPrompt()
case .identified:
    showAccountBadge()
}

There is no isIdentified property. Check authState, or add your own shortcut:

extension ChatbaseClient {
    var isIdentified: Bool {
        if case .identified = authState { return true }
        return false
    }
}

Staying Signed In

The token is saved in the Keychain (service com.chatbase.sdk, account userToken), and it can be read after the device is first unlocked. A new ChatbaseClient loads it when it is created, so the user stays signed in across app launches without calling identify again:

let client = ChatbaseClient(agentId: "YOUR_AGENT_ID")

if case .identified = client.authState {
    // Loaded from the Keychain, already signed in
}

The SDK does not check when the token expires. An expired token stays in authState until a request fails with 401 AUTH_INVALID_JWT. Handle that by getting a new token and calling identify(token:) again:

do {
    _ = try await client.send(text, conversationId: conversationId)
} catch let error as APIError where error.statusCode == 401 {
    try await client.identify(token: await AuthAPI.freshChatbaseToken())
    _ = try await client.send(text, conversationId: conversationId)
}

Calling identify(token:) on every launch where the user is already signed in is cheap, and it keeps the saved token fresh.

Identity Properties

Property	Type	Description
`deviceId`	`String`	The device ID. Always available.
`authState`	`AuthState`	`.anonymous`, or `.identified(token:)` after a successful `identify`.
`currentUserId`	`String?`	The user ID the server confirmed on the last finished reply. `nil` before that.

currentUserId comes from the end of a reply, so it appears after the first send or retry finishes, not right after identify. It is also set for anonymous users once the server assigns a user record to the device.

What Identity Changes

Once signed in, conversations belong to the user, so listConversations() returns that user’s conversations from every device they have signed in on. Without sign-in, conversations belong to the device.

logout

public func logout()

Removes the saved token and goes back to anonymous. There is no network call.

client.logout()

print(client.authState)               // .anonymous
print(client.currentUserId)           // nil
print(client.currentConversationId)   // nil
print(client.deviceId)                // unchanged

logout() also deletes the token from the Keychain and clears currentUserId and currentConversationId, so the next message starts a new anonymous conversation.

logout() does not clear message lists you are already showing. Call ConversationState.clear(), or reset your own state, at the same time, so the previous user’s messages are not left on screen.

client.logout()
state.clear()

Switching Users

To switch from one user to another, log out first so nothing carries over:

client.logout()
state.clear()
try await client.identify(token: newUserToken)

Identity Verification

Creating signed JWTs on your backend

Conversations & History

List conversations and load old messages

Error Handling

Handling expired and rejected tokens

Overview

Setup and configuration

Getting Started

Reference

Overview

Device ID

identify

AuthState

Staying Signed In

Identity Properties

What Identity Changes

logout

Switching Users

Identity Verification

Conversations & History

Error Handling

Overview

​Overview

​Device ID

​identify

​AuthState

​Staying Signed In

​Identity Properties

​What Identity Changes

​logout

​Switching Users

​Related

Identity Verification

Conversations & History

Error Handling

Overview

Overview

Device ID

identify

AuthState

Staying Signed In

Identity Properties

What Identity Changes

logout

Switching Users

Related