ExtremeX ONE — Developer Documentation

There are three equivalent ways to talk to the platform — pick per component, mix freely; they all speak the same protocol:

• Official libraries — exone-auth and exone-data from our Maven repository. Android, Kotlin/JVM, Java servers.
• JavaScript SDK — exONE for web front-ends.
• REST endpoints — plain HTTP for everything else.

1. Sign in to this portal with your ExtremeX ONE account and claim your namespace — your company's reverse domain, e.g. com.yourco.
2. Register an application (service name, display name, app type). Pick Web app / website if it runs its own browser sign-in and add a redirect URL; pick Other for a mobile, desktop or backend/service app and skip the redirect URL for now — add one later from Credentials if you ever wire up a browser flow. You receive a client_id and a client_secret — the secret is shown once, store it in a secrets manager.
3. Configure Data access: which identity fields you request, each tagged required or optional, with the reason users will read.
4. Integrate: add the library (Android/JVM), the JS SDK (web), or call the endpoints directly.
5. Watch sign-ins, grant rates and connected users live on your dashboard.

• Namespace — your reverse domain (com.yourco). All app IDs live under it. It can be renamed from the dashboard (stored data and consents migrate automatically), but every app ID under it changes — treat it as stable.
• App ID — namespace.service, e.g. com.yourco.iwish. Also the namespace for your app's user data.
• App type — Web app / website apps run their own browser-redirect sign-in and must register at least one redirect URL. Other covers mobile, desktop and backend/service apps that don't run /oauth/authorize themselves (e.g. a worker that only reads/writes App data with credentials another app obtained) — a redirect URL is optional and can be added later from the Credentials tab.
• Client ID / secret — OAuth credentials. The secret is stored hashed on our side and must live only on your server; rotate it any time from the Credentials tab.
• Data fields — the identity your app requests: first_name, last_name, avatar, email, date_of_birth (+ 18+ status), phone, address, work_email, work_phone, work_address, nationality, country_of_birth, languages, attributes (app data), offline (refresh token). Each is required or optional, with your stated reason.
• Consent — checked live on every API call. Users can withdraw optional fields (or disconnect entirely) from their ONE account at any time; your code must tolerate absent fields.
• App data — an encrypted per-user key-value store scoped to your app ID. Variables you declare are type-checked on write.
• Tokens — access tokens live 1 hour; refresh tokens (with offline) rotate on every use and die on revocation.
• Team — invite other ONE accounts to co-manage your workspace with scoped permissions and an access duration.

ExtremeX ONE implements the standard authorization-code grant:

1. Browser  →  https://one.extremextechnology.com/oauth/authorize
              ?client_id=exone_xxxxxxxx
              &redirect_uri=https://app.yourco.com/auth/callback
              &state=<random-anti-csrf-value>

2. User signs in (if needed) and reviews the consent screen:
   your required fields are locked on, optional ones can be unticked.
   The user presses Proceed.

3. Browser  ←  302 https://app.yourco.com/auth/callback?code=…&state=…

4. Your server  →  POST https://api.extremextechnology.com/one/oauth/token   (exchange, server-side only)

5. Your server  →  GET https://api.extremextechnology.com/one/oauth/userinfo (Bearer access_token)

Two rules are non-negotiable: verify state matches the value you generated, and perform the code exchange from your backend — the client secret never ships to a browser or a mobile app.

You declare data fields in this portal (app → Data access), not in the authorize URL. The consent screen renders each field with its tag and your reason:

• Required fields are pre-checked and locked — a user who proceeds grants them. Use for data your app cannot function without.
• Optional fields are pre-checked but can be unticked. Your app must handle their absence gracefully — and users can also withdraw them later from their account without disconnecting you.

The granted set is embedded in the access token and re-checked live against consents on every call: userinfo simply omits declined fields. The Data-field grants chart on your app's Overview shows exactly which optional fields users decline — honest, specific reasons measurably improve grant rates (see the consent guide).

The official ExONE libraries are served from this domain as a Maven repository. They are pure Java 8 bytecode with zero dependencies (JSON and HTTP are built in) — the same artifacts run on Android (all API levels), Kotlin/JVM, and desktop or server Java. Sources JARs are published, so IDE navigation and step-debugging work out of the box.

// settings.gradle.kts  (Android Studio / Gradle, Kotlin DSL)
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://client.extremextechnology.com/repo") }
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.extremex.one:exone-auth:1.2.0")
    implementation("com.extremex.one:exone-data:1.2.0")
}

// Groovy DSL
repositories { maven { url "https://client.extremextechnology.com/repo" } }
dependencies {
    implementation "com.extremex.one:exone-auth:1.2.0"
    implementation "com.extremex.one:exone-data:1.2.0"
}

<!-- Maven -->
<repositories>
  <repository><id>extremex</id><url>https://client.extremextechnology.com/repo</url></repository>
</repositories>
<dependency>
  <groupId>com.extremex.one</groupId><artifactId>exone-auth</artifactId><version>1.2.0</version>
</dependency>
<dependency>
  <groupId>com.extremex.one</groupId><artifactId>exone-data</artifactId><version>1.2.0</version>
</dependency>

exone-data depends on exone-auth; Gradle/Maven resolves that automatically. All network calls are blocking — on Android run them off the main thread, or use the built-in …Async variants (callbacks arrive on a background thread; hop to the main thread before touching views).

Package com.extremex.one.auth (exceptions and callbacks in com.extremex.one). Handles the entire sign-in lifecycle: building the authorize URL, exchanging the code, refreshing tokens, fetching the profile, and keeping a session alive.

ExOneAuth

The stateless client, built once and reused. Thread-safe.

ExOneTokens

ExOneUser

ExOneSession — sessions that keep themselves alive

Wraps the client + tokens and transparently refreshes the access token when it expires. Thread-safe (concurrent callers share one refresh). Because refresh tokens rotate on every use, attach a Store so rotated tokens land back in your persistence — otherwise the session dies on restart.

ExOneException & ExOneCallback

Putting it together (Kotlin, server-side handler)

val auth = ExOneAuth.builder(env("EXONE_CLIENT_ID"))
    .clientSecret(env("EXONE_CLIENT_SECRET"))
    .redirectUri("https://app.yourco.com/auth/callback")
    .build()

// GET /auth/login
val state = ExOneAuth.newState()
cookies.set("oauth_state", state); redirect(auth.authorizeUrl(state))

// GET /auth/callback?code=…&state=…
require(params["state"] == cookies["oauth_state"]) { "state mismatch" }
val tokens = auth.exchangeCode(params["code"]!!)
val user = auth.userinfo(tokens.accessToken)
val account = accounts.findOrCreateBySub(user.sub)   // stable id
sessionFor(account, tokens)

Package com.extremex.one.data. The per-user app data store: values are encrypted at rest on the platform and decrypted only for your app's authenticated requests. Requires the App data (attributes) field granted. Variables declared in your app's Create data tab are type-checked server-side on write.

ExOneData

Example (Kotlin)

val session = ExOneSession.restore(auth, stored.access, stored.refresh) { a, r ->
    stored.save(a, r)                         // rotated tokens → back to disk
}
val data = ExOneData(session)

data.write(mapOf("theme" to "dark", "level" to 3))
val streak = data.increment("streak", 1)      // 0 → 1 → 2 … per user
val prefs = data.readMap("preferences")       // null-safe typed readers

data.listAsync(object : ExOneCallback<Map<String, Any?>> {
    override fun onSuccess(all: Map<String, Any?>) = runOnUiThread { render(all) }
    override fun onError(e: ExOneException) {
        if (e.isAccessRevoked) signOutLocally()   // user disconnected the app
    }
})

Repository root: https://client.extremextechnology.com/repo · group com.extremex.one. Every artifact ships with .md5/.sha1/.sha256 checksums and maven-metadata.xml, so Gradle's dependency verification works unchanged.

Apps that ship to user devices are public clients — an APK or IPA can be decompiled, so the client secret must never be embedded in them. On every platform below, the pattern is the same:

1. Open the authorize URL in the system browser (Custom Tabs / ASWebAuthenticationSession), never an embedded WebView — users must see the real one.extremextechnology.com origin.
2. Receive the callback on an HTTPS app link / universal link registered as a redirect URL. Custom schemes like yourapp:// are not accepted.
3. Send the code to your backend, which holds the secret, performs the exchange, and returns your own session (or the tokens) to the app.

The exone-auth library enforces rule 3 for you: token calls throw unless a client secret is configured, which by design only happens server-side.

With the library (recommended):

ExOneAuth auth = ExOneAuth.builder(System.getenv("EXONE_CLIENT_ID"))
    .clientSecret(System.getenv("EXONE_CLIENT_SECRET"))
    .redirectUri("https://app.yourco.com/auth/callback")
    .build();

ExOneTokens tokens = auth.exchangeCode(code);
ExOneUser user = auth.userinfo(tokens.getAccessToken());
String sub = user.getSub();   // stable id — key your accounts on this

Or raw HTTP with java.net.http if you prefer no dependency — the token reference below has the exact payloads.

Launch the consent screen in a Chrome Custom Tab and catch the app-link callback:

// build.gradle.kts: implementation("androidx.browser:browser:1.8.0")
//                    implementation("com.extremex.one:exone-auth:1.2.0")

val auth = ExOneAuth.builder(BuildConfig.EXONE_CLIENT_ID)   // id only — never the secret
    .redirectUri("https://app.yourco.com/auth/callback")
    .build()
val state = ExOneAuth.newState()
prefs.edit { putString("oauth_state", state) }
CustomTabsIntent.Builder().build().launchUrl(context, Uri.parse(auth.authorizeUrl(state)))

// AndroidManifest.xml — the app link that brings the user back:
// <intent-filter android:autoVerify="true">
//   <action android:name="android.intent.action.VIEW" />
//   <category android:name="android.intent.category.DEFAULT" />
//   <category android:name="android.intent.category.BROWSABLE" />
//   <data android:scheme="https" android:host="app.yourco.com" android:path="/auth/callback" />
// </intent-filter>

// In the activity that receives the link:
val code = intent.data?.getQueryParameter("code")
val returned = intent.data?.getQueryParameter("state")
if (code != null && returned == prefs.getString("oauth_state", null)) {
    api.completeLogin(code)   // YOUR backend exchanges it and returns your app session
}

On JVM/Android targets use the library directly from commonMain via expect/actual, or keep flow logic common with Ktor; only opening the browser is platform-specific:

// commonMain
class OneAuth(private val client: HttpClient, private val backend: String) {
    fun authorizeUrl(state: String) =
        "https://one.extremextechnology.com/oauth/authorize" +
        "?client_id=$CLIENT_ID&redirect_uri=$REDIRECT_URI&state=$state"

    suspend fun completeLogin(code: String): Session =
        client.post("$backend/auth/exchange") {   // your server does the secret exchange
            contentType(ContentType.Application.Json)
            setBody(mapOf("code" to code))
        }.body()
}

// expect/actual — the only per-platform piece:
expect fun openBrowser(url: String)
// androidMain → CustomTabsIntent.launchUrl(...)
// iosMain     → ASWebAuthenticationSession (Swift section below)
// desktopMain → Desktop.getDesktop().browse(URI(url))

• React Native / Expo — expo-auth-session or react-native-app-auth pointed at the authorize URL; exchange the code on your backend exactly as above.
• Desktop (Electron, Tauri, JavaFX, .NET) — open the authorize URL in the default browser and listen on http://localhost:<port>/callback (accepted for development); production desktop apps should still exchange through your backend. JavaFX/Swing apps can use the library directly.
• Server-rendered web (PHP, Django, Rails, Go, …) — confidential clients: run the whole flow server-side; any HTTP client works.
• CLI tools — print the authorize URL, listen on localhost, exchange via your backend or (internal tools) with the secret from the machine's environment.

With the attributes field granted, your app gets a private key-value store per user, namespaced to your app ID — no application can read another's keys. Values are encrypted at rest (AES-256-GCM, a key derived per app) and decrypted only for your app's requests carrying an authenticated user's token with live consent — not for the portal, not for other apps, not for a database dump.

GET    https://api.extremextechnology.com/one/data            → list all keys (decrypted)
GET    https://api.extremextechnology.com/one/data?key=k      → read one key
PUT    https://api.extremextechnology.com/one/data            → { "data": { "k": v, … } } write/merge (≤100 keys)
DELETE https://api.extremextechnology.com/one/data?key=k      → remove a key
(all with Authorization: Bearer <access_token>)

In your app's Create data tab, declare the variables your app stores — a name, a type (string, number, boolean, date (ISO string), json), and a description. Writes to a declared variable are type-checked server-side and rejected with 400 Type mismatch on violation; undeclared keys stay free-form. Declare your schema early — it turns a whole class of client bugs into loud development-time errors instead of silent bad data.

The shortest path for a web app with a JVM backend. (Other stacks: same three steps, different syntax — see platforms.)

1. Register your app on the dashboard as a Web app / website; set the production redirect URL and (for dev) a http://localhost:… one — required for this app type since it drives its own sign-in.
2. Configure Data access — start minimal: name required, email optional with an honest reason.
3. Wire two routes with the library (see the full example): /auth/login generates state and redirects to authorizeUrl(state); /auth/callback verifies state, calls exchangeCode, then userinfo, and matches your local account by user.sub.

Handle the two “unhappy” paths from day one: the user pressing Cancel (?error=access_denied on your callback) and a declined optional field (user.getEmail() == null — offer value, don't nag).

1. Request the Stay signed in (offline) field in Data access — the token response then includes a refresh_token.
2. Wrap tokens in an ExOneSession with a Store — refresh tokens rotate on every use, and the Store is how the rotated pair reaches your persistence. Missing this is the #1 integration bug: everything works until the first restart, then every session is dead.
3. On isAccessRevoked() (or HTTP 403 access_revoked): the user disconnected you from their ONE account. Delete stored tokens, show the signed-out state, re-run sign-in when they return.

// App start:
val session = ExOneSession.restore(auth, disk.access, disk.refresh) { a, r -> disk.save(a, r) }
// From here, session.userinfo() / ExOneData(session) never hand you a stale token.

1. Declare variables in Create data (e.g. level: number, preferences: json) — get type errors in development, not corrupt data in production.
2. Request the App data field (required if your app can't work without it).
3. Use ExOneData (or exONE.data on web): typed reads, batch writes, increment() for counters.

What belongs here: settings, progress, preferences, lightweight state — anything per-user that you'd otherwise stand up a database table for. What doesn't: data shared between users, large blobs (16 KB/value cap), or anything you need to query across users — that's your own database's job.

• Mark required only what is truly required. An app that requires everything reads as greedy; grant rates drop.
• Write reasons users understand. “To email your receipts” beats “for communication purposes”.
• Ask late if you can. Start with name only; re-run the authorize flow when a feature actually needs email — users grant more when the context is obvious.
• Watch the numbers. The Data-field grants chart on your Overview shows exactly which optional fields users decline.
• Remember withdrawal. Users can untick optional fields later from their ONE account without disconnecting — treat every optional field as possibly-absent on every call, not just the first.

A game: identity + progress, no backend database

Request name (required — leaderboard identity), attributes (required — save games) and offline (optional — resume without re-login). Declare high_score: number, level: number, save: json. Use increment("games_played", 1) per round and write("save", state) on checkpoint. Result: full player persistence with zero server infrastructure of your own.

A SaaS tool: one identity across your product suite

Register each product as its own app under your namespace (com.yourco.crm, com.yourco.billing) — one ONE account signs into all of them, while consents, data namespaces and analytics stay cleanly per-app. Use the Team feature to give engineers scoped access (e.g. credentials but not delete) with a 1-year expiry that matches contractor terms.

A cross-device consumer app: settings that follow the user

Web front-end uses the JS SDK, Android uses exone-auth/exone-data, both write the same preferences: json variable — the user changes their theme on the phone and the web app has it on next load. No sync service to build.

An internal tool: staff sign-in in an afternoon

Register com.yourco.admin as a Web app / website with name + email required, redirect to your intranet host, and gate your routes on a verified sub allowlist. The consent screen, session management, and audit trail come from the platform.

A mobile app: register before you build the sign-in screen

Building the Android client and its data model before wiring up sign-in? Register it as Other and skip the redirect URL — you get a client_id/client_secret immediately and can start on App data. Come back to Credentials and add the https://…/auth/callback app-link redirect (see Mobile & native) once you build the actual /oauth/authorize call — every app that signs users in of its own accord needs at least one registered redirect URL before that call will work.

1. If your app signs users in directly (app type Web app / website, or any native app calling /oauth/authorize): production redirect URL registered (HTTPS); dev localhost URL removed.
2. Secret in a secrets manager; CI has no access; rotate it if it ever touched a repo.
3. state generated and verified in the callback.
4. 401 → refresh, 403 access_revoked → local sign-out, declined-optional-field paths all tested.
5. Icon, description and website set (Settings) — they appear on the consent screen.
6. Data-access reasons reviewed — clear, honest, specific.
7. Your privacy policy covers the ONE data you receive — see the legal hub.
8. Post-launch: watch sign-ins, grant rates and active sessions on the dashboard.

• Keep the client secret in server-side configuration only; rotate it from the Credentials tab if it may have leaked.
• If your app runs its own sign-in flow, register exact redirect URLs — no wildcards, and use localhost only for development. Apps that never call /oauth/authorize themselves (app type Other) can skip this entirely.
• Always send and verify state; the library's ExOneAuth.newState() gives you a safe value.
• Treat sub as the user's primary key; emails can change or be withdrawn.
• Request the minimum data set; mark optional everything your app can work without.
• On access_revoked, stop processing and delete cached ONE data for that user within 30 days (see Terms).
• Report suspected credential leaks to [email protected] and rotate immediately.