Sign in with KRDPASS (App-to-App): Reference

Detailed technical reference for Sign in with KRDPASS (app-to-app) integration. Use this page for lookups — not linear reading.

Endpoint Contracts

The reference backend (examples/server) implements these endpoints. Your production backend should follow the same contract.

OpenAPI Specification

You can download the full OpenAPI 3.0 specification for these endpoints to generate your backend client: Download cas-oauth-endpoints.json

POST /oauth/par

Creates a signed Pushed Authorization Request (PAR) and returns a requestUri for the SDK.

Request:

{
  "codeChallenge": "<pkce_code_challenge>",
  "codeChallengeMethod": "S256",
  "state": "<secure_random_state>",
  "nonce": "<secure_random_nonce>",
  "environment": "development",
  "redirectUri": "https://app-link.example.com/_krdpass/oauth/callback",
  "scope": "openid profile citizen_identity"
}

Response:

{
  "requestUri": "urn:ietf:params:oauth:request_uri:...",
  "expiresIn": 300,
  "state": "<secure_random_state>"
}

POST /oauth/token

Exchanges an authorization code + PKCE verifier for tokens.

Request:

{
  "code": "<authorization_code>",
  "state": "<secure_random_state>",
  "codeVerifier": "<pkce_code_verifier>",
  "environment": "development",
  "redirectUri": "https://app-link.example.com/_krdpass/oauth/callback"
}

Response:

{
  "accessToken": "...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "refreshToken": "...",
  "idToken": "...",
  "scope": "openid profile offline_access"
}

Optional Endpoints

• POST /oauth/token/refresh
• POST /oauth/token/revoke

Environment Variables

Server .env configuration:

Variable	Example	Required	Notes
CLIENT_ID	your-client-id	Yes	Issued during onboarding
CLIENT_SECRET	your-secret	Yes	Server-side only
RSA_PRIVATE_KEY	escaped PEM string	Yes	Server-side only
HOST	127.0.0.1	No	Defaults to 127.0.0.1
PORT	3000	No	Defaults to 3000
ALLOWED_REDIRECT_HOSTS	app-link.example.com	No	Recommended for security

Convert PEM to .env format

awk 'NF {sub(/\r/,""); printf "%s\\n",$0;}' private-key.pem

Result:

RSA_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

Server Security Behavior

The reference server enforces:

• Canonical environment values: development and production (aliases like dev/prod are resolved)
• Rejects client attempts to override auth server URL
• Requires HTTPS redirectUri
• Optional redirect host allowlist (ALLOWED_REDIRECT_HOSTS)
• Requires codeChallengeMethod = S256
• RFC 7636 format validation:
  • codeChallenge: base64url, 43–128 chars
  • codeVerifier: unreserved charset, 43–128 chars
• Length bounds on state, nonce, scope, code, and token inputs
• Server-side state storage with one-time use enforcement
• state bound to original redirectUri (checked on token exchange)
• Cache-Control: no-store on OAuth endpoints

Scope Policy

Scope	What you get	Approval
openid	Subject identity (sub), standard claims (iss, aud, exp, iat)	Baseline
profile	Basic profile claims	Baseline
citizen_identity	citizen_first, citizen_second, citizen_third, citizen_surname, birthdate, sex_at_birth, did, citizen_profile_picture	Requires approval
offline_access	Refresh token issuance	Requires explicit approval

• Baseline scopes: openid profile
• Identity scopes require approval
• offline_access is restricted by default for first integrations

Redirect URI

Use one HTTPS redirect URL that launches back into your app. This is the app-launch callback URL (Universal Link), not your backend API URL.

Keep the exact same redirect URL in:

• Your app config
• Your backend .env
• Your KRDPASS onboarding registration

iOS: Universal Links & AASA

For iOS callback delivery, your redirect host must:

1. Be configured in Associated Domains: applinks:<host>
2. Serve AASA at: https://<host>/.well-known/apple-app-site-association

Minimal AASA example

{
  "applinks": {
    "apps": [],
    "details": [{
      "appID": "<TeamID>.<BundleID>",
      "paths": ["/_krdpass/*"]
    }]
  }
}

Serve as application/json with no redirects.

Finding your Team ID and Bundle ID

1. Open project in Xcode
2. Select target → Signing & Capabilities
3. Copy Team (Apple Team ID) and Bundle Identifier

Android SHA-256 Fingerprint

Register your SHA-256 fingerprint during onboarding.

Generate a release keystore

keytool -genkeypair \
  -v \
  -keystore myapp-release.jks \
  -alias myapp-release \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000

Extract SHA-256 fingerprint

keytool -list -v \
  -keystore myapp-release.jks \
  -alias myapp-release

Copy the SHA256: value and submit it in your onboarding request.

Sync Scripts Reference

Script	What it does
scripts/sync-secrets.sh	Syncs shared/secrets/.env to all sample app configs
scripts/sync-secrets-android.sh	Android-only sync
scripts/sync-secrets-ios.sh	iOS-only sync
scripts/run-sample.sh	Runs server or sample apps

Files updated by sync

• examples/server/.env
• packages/krdpass_auth_flutter/example/.env
• packages/krdpass_auth_react_native/example/.env
• packages/*/example/**/key.properties (Android signing)
• iOS associated-domain entries and sample bundle identifiers

Example App Config Files

SDK	Config file	Template
Flutter	packages/krdpass_auth_flutter/example/.env	env.example
Android	packages/krdpass_auth_android/example/config.properties	config.properties.example
iOS	Xcode scheme environment variables	packages/krdpass_auth_ios/example/env.example
React Native	packages/krdpass_auth_react_native/example/.env + app.json	.env.example

Flutter .env keys

CLIENT_ID=your-client-id
REDIRECT_URI=https://app-link.example.com/_krdpass/oauth/callback
BACKEND_URL=https://auth-api.example.com
CAS_AUTH_SERVER_URL=https://auth.dev.krd
CAS_TOKEN_URL=https://auth.dev.krd/connect/token
CAS_PAR_URL=https://auth.dev.krd/connect/par

Android config.properties

backendUrl=https://auth-api.example.com
redirectUri=https://app-link.example.com/_krdpass/oauth/callback
clientId=your-client-id
environment=development

iOS environment variables

KRD_CLIENT_ID
KRD_REDIRECT_URI
KRD_BACKEND_URL
KRD_ENVIRONMENT

React Native environment variables

EXPO_PUBLIC_CLIENT_ID
EXPO_PUBLIC_REDIRECT_URI
EXPO_PUBLIC_BACKEND_URL
EXPO_PUBLIC_KRD_ENVIRONMENT (canonical: development or production)

Contact

Integration support	integration@pass.krd
Security reports	security@pass.krd