Effective Date: September 19, 2026

Last Updated: September 19, 2026

Platform Provider: Startum Identity Platform ("Startum", "we", "us", or "our")

---

1. Overview & Architectural Principles

These App Developer Guidelines outline best practices, security requirements, and technical standards for integrating your web, mobile, desktop, or microservice application with the Startum OpenID Connect (OIDC) & OAuth 2.0 Identity Platform.

Startum provides secure single sign-on (SSO) with Pairwise Subject Privacy, RFC 7636 Proof Key for Code Exchange (PKCE), standard JSON Web Tokens (JWT), and standard OIDC user claims.

---

2. Integration Guides

Developers can integrate Startum using either the Official Node.js SDK (Recommended for Node.js / Express) or the Manual OAuth 2.0 + PKCE Protocol (for Python, Go, Rust, Mobile, or custom runtimes).

Guide 1: Integration via Official Node.js SDK (@startum/auth-node)

The official SDK handles PKCE key pair generation, SHA-256 code challenge computation, state verification, HTTP cookie management, and token exchange automatically in 2–3 lines:

npm install https://startum.cloud/startum-auth-node.tgz

const express = require('express');
const cookieParser = require('cookie-parser');
const { startumAuth } = require('@startum/auth-node');

const app = express();
app.use(cookieParser());

const auth = startumAuth({
  clientId: process.env.STARTUM_CLIENT_ID,
  clientSecret: process.env.STARTUM_CLIENT_SECRET, // optional for public clients
  redirectUri: 'https://my-app.com/callback'
});

// 1. Initiates PKCE and redirects user to Startum
app.get('/login', auth.redirect());

// 2. Validates state, exchanges code with PKCE & fetches user profile
app.get('/callback', auth.handleCallback(async (user, tokens, req, res) => {
  req.session.userId = user.sub;
  res.redirect('/dashboard');
}));

---

Guide 2: Manual Integration via OAuth 2.0 + PKCE Protocol (RFC 7636)

For non-Node.js platforms (Python, Go, Rust, Ruby, PHP, Swift, Kotlin) or custom HTTP clients, follow the manual protocol steps below:

1. Generate code_verifier: Generate a high-entropy cryptographically random Base64URL string (43–128 characters using [A-Z, a-z, 0-9, -, ., _, ~]).
2. Calculate code_challenge: Derive the SHA-256 hash of code_verifier and Base64URL encode without padding:

$$\text{code\_challenge} = \text{Base64URL}(\text{SHA-256}(\text{code\_verifier}))$$

3. Pass code_challenge_method=S256: Redirect the user to the authorization endpoint:

GET https://startum.cloud/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback
  &scope=openid%20profile%20email
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=RANDOM_STATE_STRING

1. Verify State & Exchange Code: On callback, verify that state matches your stored cookie state, then POST to the token endpoint:

POST https://api.startum.cloud/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code=AUTHORIZATION_CODE
&code_verifier=YOUR_CODE_VERIFIER
&redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback

Client Types & Secrets:

Public Clients (SPAs, Mobile, Desktop): client_secret is optional and omitted when using PKCE. The token endpoint verifies the authorization code using code_verifier alone.

Confidential Clients (Backend-Only Servers): client_secret is mandatory alongside code_verifier. If using popup or browser-based authentication flows, the popup message handler must pass the authorization code and verifier to your backend server rather than exchanging tokens directly in the browser, ensuring your client_secret is never exposed.

---

3. Client Credential & Token Management

• Confidential Clients: Confidential web backends (Express, Next.js API, Django, Rails) must keep the client_secret confidential. Never commit client secrets to git or transmit them to frontend clients.
• Public Clients: SPAs, native mobile apps, and CLI applications must select Public Client during app registration. Public clients do not require or use a client_secret, relying entirely on PKCE validation.
• Token Storage Standards:

Web Servers: Store access/refresh tokens in server-side session stores or encrypted, HttpOnly, Secure cookies. Do not store raw tokens in browser localStorage or sessionStorage.

Native Applications: Store refresh tokens in platform secure storage (iOS Keychain, Android Keystore, Windows Credential Manager, macOS Keychain).

---

4. Identity Claims & Scope Minimization

Startum enforces the principle of data minimization. Request only the OIDC scopes required for your application's functionality:

---

5. Pairwise Subject Privacy Rules

• Startum generates a unique sub for each application.
• Do not attempt to merge user identity profiles across different Client IDs by matching sub values, as sub values are cryptographically non-linkable between apps.
• Use email (if requested and verified) as the canonical match key when performing user identity reconciliation across multiple OAuth providers.

---

6. Brand Usage & UI Guidelines

When providing Startum SSO inside your application interface:

• Use official "Continue with Startum" or "Sign in with Startum" SSO brand buttons.
• Maintain official button dimensions, font styles, and Startum icon colors (Startum Blue #7F8CFF).
• Include light and dark mode variants appropriate for your application UI theme.
• Do not alter the Startum trademark logo or icon geometry.

---

7. Compliance Checklist Before Launch

Before launching your app into production:

• [ ] Registered exact, full HTTPS redirect URIs in the Startum Developer Portal.
• [ ] Implemented PKCE SHA-256 (code_challenge_method=S256).
• [ ] Validated state parameter to prevent CSRF attacks.
• [ ] Secured client_secret in environment variables or key vaults.
• [ ] Added links to your App's Privacy Policy and Terms of Use on your login page.
• [ ] Tested token refresh logic and authorization code expiry handling.

---

8. Developer Support & Questions

For developer support, OAuth integration help, or API policy inquiries:

• Email Support: [email protected]
• Privacy & Security Concerns: [email protected]