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. For production integrations, wait for the matching public Maven > Central artifact. A Workspace release alone does not guarantee a publicly > available SDK package with the same version. Until then, the following steps > are an advance reference.

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)
    AuthStates.LICENSE_AGREEMENT_REQUIRED -> showAgreementNotice(result.agreement)
}

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.

For AuthStates.LICENSE_AGREEMENT_REQUIRED, the SDK returns read-only agreement metadata. canAccept reports whether the identity may accept the agreement in the protected browser flow. Regardless of that value, Workspace does not issue a session or bootstrap grant in this state. Continue through your configured Workspace browser flow. Do not derive a URL from agreement.routeKey; the SDK deliberately provides no headless acceptance action.

Execute server actions

A resource entrypoint can contain structured actions instead of a direct HTTP method. Select an action by its stable ID and call executeAction(). Supply exactly the headers advertised in requiredHeaders. The SDK verifies the expected status and returns only the response headers allowed by responseHeaders.

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.