Getting started

Before you start. Solibo issues app and machine clients: write to solibohome@solibo.no as described in Getting credentials. Solibo sets up your client, and the board of each housing community (API: company) approves its access to that community. A service or integration uses a machine client (JVM or Node); an app where people sign in uses an app session (Android, iOS, desktop, CLI). There is no public sandbox: try read-only calls with your own Solibo Home account in Swagger first. Machine clients start with read scopes.

Session TypeScript auth.kind React authMode Kotlin factory
Machine client: services and integrations m2m AuthMode.M2M SoliboSDK.createM2M
App session: Android, iOS, desktop, CLI mobile AuthMode.TOKEN SoliboSDK.createMobile
Cookie session: pages Solibo hosts browser AuthMode.COOKIE SoliboSDK.createBrowser

Kotlin users pick a factory; it sets AuthMode for you. The developer portal shows what each session sends over the wire. The SDK connects to https://api.home.solibo.no by default.

Install

Kotlin (Android, iOS, JVM)

Add the dependency to your module’s build.gradle.kts. In a KMP project, add it to commonMain.dependencies.

repositories {
    mavenCentral()
}

dependencies {
    implementation("no.solibo.oss:sdk:1.26.12")
}

iOS: the SDK reaches iOS through Kotlin Multiplatform. Add the dependency to a KMP module and call it from Swift through that module’s framework; there is no separate Swift package or CocoaPod.

TypeScript 

npm install @solibo/solibo-sdk

The TypeScript package runs in browsers and on Node.

Services and integrations

A service or integration uses a machine client with a client id and secret. Keep the secret on the server. List the housing communities your client can reach, then read one:

import no.solibo.oss.sdk.SoliboSDK

val sdk = SoliboSDK.createM2M(
    clientId = "YOUR_CLIENT_ID",
    clientSecret = System.getenv("SOLIBO_CLIENT_SECRET"),
)

// Inside a coroutine. The client fetches its token on the first call.
// Needs the read, company:list and company:show scopes. .body() decodes the response;
// the wrapper also carries status and headers.
val page = sdk.api.companies.indexCompany().body()
val first = page.items.firstOrNull() ?: error("No housing community has approved this client yet")
val company = sdk.api.companies.showCompany(companyId = first.id).body()
println(company.name)

import { createSoliboClient } from '@solibo/solibo-sdk'

const sdk = createSoliboClient({
  auth: {
    kind: 'm2m',
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: process.env.SOLIBO_CLIENT_SECRET!,
  },
})

// In an async function. The client fetches its token on the first call.
// Needs the read, company:list and company:show scopes. Returns the body; throws SoliboApiError.
const page = await sdk.api.companies.indexCompany({})
if (page.items.length === 0) throw new Error('No housing community has approved this client yet')
const company = await sdk.api.companies.showCompany({ companyId: page.items[0].id })
console.log(company.name)

In Kotlin, leave out fields here: a plain string selects the full model, and decoding fails when required fields are missing. Use ProjectionFields instead (see Field projections). Use orgNr to match housing communities to your own records. sdk.api.users.me() (TypeScript: me({})) returns the identity the API sees, a quick check that your credentials work.

Leave scopes out to get everything your client was granted. Passing scopes (for example listOf("read") or ['read']; the solibo-home/ prefix is optional) limits only the scopes in the token itself; scopes Solibo grants your client directly still apply.

A machine client acts as your integration, with the housing communities and scopes granted to it, not as the person using your product. Web products on other domains call the API from their own server this way; browsers on other domains cannot call it directly.

Apps where people sign in

An app session signs a person in and refreshes their tokens for you. Create one SDK instance for your app:

import no.solibo.oss.sdk.SoliboSDK

val sdk = SoliboSDK.createMobile(
    userPoolId = "YOUR_USER_POOL_ID",
    clientId = "YOUR_CLIENT_ID",
)

See Advanced setup to connect device fingerprinting and push notifications.

import { createSoliboClient } from '@solibo/solibo-sdk'

const sdk = createSoliboClient({
  auth: {
    kind: 'mobile',
    userPoolId: 'YOUR_USER_POOL_ID',
    clientId: 'YOUR_CLIENT_ID',
  },
})

The user pool id comes with your app client credentials. Complete the authentication flow, including any required password or MFA challenge, then make the same calls as in Services and integrations. See Calling conventions for how parameters and request bodies are passed.

Pages Solibo hosts on solibo.no

A cookie session (kind: 'browser') uses the Solibo Home session cookies. They reach only https://home.solibo.no/api, and only from Solibo-hosted pages whose origin the API allows (home, developers, swagger and async.solibo.no). Set baseUrl: 'https://home.solibo.no' and credentials: 'include' (React: domain: 'home.solibo.no', credentials: 'include'). Pages on other origins cannot call the API at all; call it from your server with a machine client.

import { createSoliboClient } from '@solibo/solibo-sdk'

const sdk = createSoliboClient({
  baseUrl: 'https://home.solibo.no', // the client adds /api
  auth: {
    kind: 'browser',
    userPoolId: 'YOUR_USER_POOL_ID',
    clientId: 'YOUR_CLIENT_ID',
    credentials: 'include',
  },
})

React 

npm install @solibo/solibo-sdk @solibo/solibo-react @tanstack/react-query

Requires React 19 and TanStack Query 5. Wrap your app once. Import models and client APIs from @solibo/solibo-sdk, and hooks from @solibo/solibo-react.

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { AuthMode } from '@solibo/solibo-sdk'
import { SoliboProvider, type CreateSdkArgs } from '@solibo/solibo-react'

const queryClient = new QueryClient()
const config: CreateSdkArgs = {
  authMode: AuthMode.COOKIE,
  cognitoUserPoolId: 'YOUR_USER_POOL_ID',
  clientId: 'YOUR_CLIENT_ID',
  domain: 'home.solibo.no',
  credentials: 'include',
}

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <SoliboProvider config={config}>
        <YourAppContent />
      </SoliboProvider>
    </QueryClientProvider>
  )
}

SoliboProvider takes the builder options (authMode, cognitoUserPoolId, domain, credentials), which mean the same as auth.kind, userPoolId, baseUrl and credentials in createSoliboClient. The provider rebuilds the client when one of its tracked options changes identity, for example an inline refreshFailureHandler, fingerprinter or scopes array, so define those at module scope or with useMemo. A change to credentials alone is not picked up. Inside a component, useSoliboApi() gives you the configured client (useSdk and SdkProvider are aliases).

For TanStack Query with another framework, install @solibo/solibo-query and @tanstack/query-core alongside the SDK. See query options.

Next steps

Solibo AS