# Suloro for Developers (developers.suloro.com)

> Machine-Readable Identity & Single Sign-On (SSO) Knowledge Base for LLMs, AI Agents (Antigravity, Cursor, Windsurf, Copilot), and Vibe Coding.

## System Overview & Current Versions
- **Current SDK Version:** `1.1.3` (Latest Production)
- **Identity Provider Endpoint:** `https://accounts.suloro.com/signin`
- **Developer Console:** `https://accounts.suloro.com/developer` (Register Client IDs, URIs, and SHA-256 fingerprints)
- **Android Maven Repository:** `https://dl.suloro.com/android`
- **Android SDK Artifact:** `com.suloro.android:auth:1.1.3` (Min SDK 24+, Target SDK 34+)
- **Documentation:** `https://developers.suloro.com`
- **Full LLM Reference:** `https://developers.suloro.com/llms-full.txt`

---

## Core Architecture Principles
1. **Zero-Config OAuth:** No manual OAuth scope strings (`scope=name+email`) required. Claims configured in the Developer Console are automatically cryptographically asserted and released.
2. **Standard Parameters:**
   - `client_id`: Application ID from Developer Console (`app_...` for Web, Android client ID for Android).
   - `redirect_uri`: Whitelisted callback URL on your domain.
   - `platform`: `web` or `android`.
3. **Instant Handshake:** Local cached session checks with zero advertising tracking cookies.

---

## Web Integration Cheatsheet (Copy & Paste for AI / Vibe Coders)

### 1. 1-Click Popup Auth Flow (Recommended)
```javascript
// Function to launch popup auth
function loginWithSuloro() {
  const CLIENT_ID = "YOUR_WEB_CLIENT_ID";
  const REDIRECT_URI = window.location.origin + "/popup-callback.html";
  const authUrl = `https://accounts.suloro.com/signin?client_id=${encodeURIComponent(CLIENT_ID)}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&platform=web`;
  
  const popup = window.open(authUrl, "SuloroAuth", "width=500,height=650,top=100,left=100");
  
  window.addEventListener("message", (event) => {
    if (event.origin !== window.location.origin) return;
    if (event.data?.type === "SULORO_AUTH_SUCCESS") {
      const { user, token } = event.data.payload;
      console.log("Verified User:", user.name, user.email, user.uid);
    }
  });
}
```

### 2. Popup Callback Page (`popup-callback.html`)
```html
<!DOCTYPE html>
<html>
<head><title>Authenticating...</title></head>
<body>
<script>
  try {
    const params = new URLSearchParams(window.location.search);
    const rawPayload = params.get('payload');
    if (rawPayload && window.opener) {
      window.opener.postMessage({
        type: 'SULORO_AUTH_SUCCESS',
        payload: JSON.parse(decodeURIComponent(rawPayload))
      }, window.location.origin);
      window.close();
    }
  } catch (err) {
    if (window.opener) {
      window.opener.postMessage({ type: 'SULORO_AUTH_ERROR', error: err.message }, window.location.origin);
      window.close();
    }
  }
</script>
</body>
</html>
```

### 3. Silent Auto-Login / Session Check (`action=check_session`)
```javascript
function checkSuloroSession(clientId, callback) {
  const iframe = document.createElement('iframe');
  iframe.style.display = 'none';
  iframe.src = `https://accounts.suloro.com/?action=check_session&client_id=${encodeURIComponent(clientId)}&redirect_uri=${encodeURIComponent(window.location.origin + '/popup-callback.html')}&platform=web`;
  
  window.addEventListener('message', function onMessage(e) {
    if (e.data?.type === 'SULORO_SESSION_RESULT') {
      window.removeEventListener('message', onMessage);
      iframe.remove();
      callback(e.data.status === 'authenticated', e.data.payload);
    }
  });
  document.body.appendChild(iframe);
}
```

---

## Android SDK v1.1.3 Integration Cheatsheet (Kotlin & Compose)

### 1. Repository Setup (`settings.gradle.kts`)
```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://dl.suloro.com/android") }
    }
}
```

### 2. Dependency Setup (`build.gradle.kts`)
```kotlin
dependencies {
    implementation("com.suloro.android:auth:1.1.3")
}
```

### 3. Application Initialization (`Application.onCreate` or `MainActivity.onCreate`)
```kotlin
// Tip: Set loadInStart = true for fast instant sheet opening when the app is lightweight
SuloroAuth.init(
    SuloroAuthConfig(
        clientId = "YOUR_ANDROID_CLIENT_ID",
        loadInStart = true // Pre-warms auth engine on app startup
    )
)
```

### 4. Jetpack Compose Integration
```kotlin
@Composable
fun SuloroLoginScreen(onSuccess: (SuloroUser) -> Unit) {
    val authLauncher = rememberLauncherForActivityResult(SuloroAuthContract()) { result ->
        when (result) {
            is SuloroAuthResult.Success -> onSuccess(result.user)
            is SuloroAuthResult.Error -> Log.e("Auth", "Error: ${result.error.message}")
            is SuloroAuthResult.Cancelled -> Log.d("Auth", "User cancelled")
        }
    }

    Button(onClick = {
        authLauncher.launch(SuloroAuthConfig(clientId = "YOUR_ANDROID_CLIENT_ID", loadInStart = true))
    }) {
        Text("Sign in with Suloro")
    }
}
```

### 5. Kotlin ViewBinding Integration
```kotlin
binding.btnSuloroLogin.setOnClickListener {
    SuloroAuth.getInstance().signIn(this, object : SuloroAuthCallback {
        override fun onSuccess(user: SuloroUser) {
            Log.d("Auth", "Welcome ${user.name} (${user.email})")
        }
        override fun onError(error: SuloroAuthError) {
            Toast.makeText(this@MainActivity, error.message, Toast.LENGTH_SHORT).show()
        }
    })
}
```

### 6. Silent Session Routing (`checkSession`)
```kotlin
// Fast startup routing without blocking UI
SuloroAuth.getInstance().checkSession(this, forceNetworkCheck = false, object : SuloroSessionCallback {
    override fun onAuthenticated(user: SuloroUser) {
        // Fast instant routing to main dashboard
        startActivity(Intent(this@SplashActivity, DashboardActivity::class.java))
    }
    override fun onUnauthenticated() {
        // Show login screen
    }
})
```

---

## User Profile Claims Schema
Every authenticated response returns verified claims automatically:
- `uid`: Unique immutable string (e.g. `usr_89f1a7b`).
- `name`: Full display name string.
- `email`: Verified primary email address.
- `gender`: Gender identity string (`Female`, `Male`, `Other`).
- `dateOfBirth`: Date string (`YYYY-MM-DD`).
- `age`: Integer full years (e.g. `24`).
- `photoUrl`: HTTPS avatar URL.
- `accessToken`: Secure bearer token for backend validation.

---

## Standard Error Codes & Diagnostics
- `UNTRUSTED_CLIENT`: The `client_id` is invalid or missing in Developer Console. Check `https://accounts.suloro.com/developer`.
- `REDIRECT_URI_MISMATCH`: The requested `redirect_uri` does not match the whitelist in Developer Console.
- `CROSS_PLATFORM_MISMATCH`: Web client ID used on Android or Android client ID used on Web.
- `PLAY_INTEGRITY_FAILED`: Android APK SHA-256 certificate fingerprint does not match the Developer Console registration.