Set up the Workspace Android SDK

Use the official Android SDK to connect a custom Workforce or Admin app to Workspace. This quickstart is for Android developers. After completing it, your app discovers the server contract, runs headless login, and stores the session encrypted.

> Choose the Android SDK for native Kotlin and Java apps. Flutter is not part of the supported SDK surface yet. Server-side integrations use the release-bound Go, Node.js, and PHP SDKs after the required version is available in its package registry.

> The Android SDK is prepared for Maven Central but has not been published > there yet. Until the first release has passed its external consumer test, > use the local Maven repository produced by the release dry run. A Workspace > release alone does not guarantee a publicly available SDK package with the > same version.

Prerequisites

  • Android API 26 or newer
  • a Workspace installation reachable over HTTPS
  • a Workforce or Admin user
  • the same version number for Workspace and the SDK

Add the dependency

kotlin
dependencies {
    implementation("com.schukai.nucleus:nucleus-sdk-android:<workspace-version>")
}

Do not select an SDK version independently. Each Workspace release produces the matching SDK contract and Maven artifacts.

Create the client

kotlin
val sessions = AndroidSecureSessionStore(applicationContext)
val nucleus = NucleusClient.create("https://workspace.example.com/", sessions)
val discovery = nucleus.discover()

Check discovery.apiMajor before continuing. Enable optional behavior only through capabilities and published entrypoints. Do not infer capabilities from serverVersion.

Sign in

kotlin
val result = nucleus.login(email, password)
when (result.state) {
    AuthStates.READY_SESSION -> openWorkspace(result.activeTenantId)
    AuthStates.CHALLENGE_REQUIRED -> requestSecondFactor(result.challenge!!.token)
    AuthStates.SELECTION_REQUIRED -> showTenants(result.tenantCandidates)
}

The SDK stores an issued session with Android Keystore and AES-GCM. Never log passwords, session or challenge tokens, bootstrap grants, cookies, or complete error responses.

Verify the result

The setup is complete when discover() returns API major v1 and login() returns a documented authentication state. After AuthStates.READY_SESSION, resourceEntrypoints() returns only the resources allowed for the current user and tenant.

Handle failures through the HTTP status and stable errorCode. Localize the user-facing message in your app; this SDK version intentionally ships no runtime translations.