SeleReference
Errors and security notes
Overview · React Native and Expo · Android · iOS · Register an app · API reference · Errors and security · Changelog
Coming soon @seletech/seleid-client is not on npm yet. These pages describe version 0.1.0 so you can plan an integration. See the roadmap.
Errors
Every failure is a SeleIdError. Branch on error.kind only. Useful fields: kind, code (SeleID error code), status, requestId, retryAfter (seconds), correlationId. Messages never contain tokens or personal data. isSeleIdError(value) narrows an unknown value.
kind | Meaning | What your app does |
|---|---|---|
timeout | Hard timeout hit | Unknown outcome. Keep tokens. Retry later; sensitive actions stay blocked |
network | No connection or no fetch | Same as timeout |
unavailable | 5xx, temporarily_unavailable, context_timeout, token storage unreadable | Same as timeout |
unauthenticated | No session, malformed or expired token, rejected code | Sign in again (a refresh is tried automatically for an expired token) |
revoked | session_revoked, invalid_grant, generation mismatch | Session is over: tokens cleared, go to sign-in |
disabled | account_disabled, account_suspended, account_banned, unknown status | Session is over: tokens cleared |
deleted | account_deleted | Session is over: tokens cleared |
recovering | account_recovering | Send the person to account recovery |
forbidden | forbidden, invalid_client, HTTP 403 | Check client id and registration; do not retry |
rate_limited | rate_limited, HTTP 429 | Wait retryAfter seconds |
conflict | conflict (for example a preferences version clash) | Reload and retry the change |
invalid_request | invalid_request, unsupported_grant_type, not_found, method_not_allowed, payload_too_large | Fix the call; do not retry |
schema_mismatch | Response did not match the contract | Report a bug; treat as unknown |
crypto_unavailable | No crypto.subtle | Pass a CryptoPort to createVerifier |
Helpers: error.isUnknown is true for timeout, network and unavailable (fail closed on sensitive actions, keep the screen usable). error.endsSession is true for revoked, disabled and deleted. A 5xx is always unavailable, whatever the body says.
Security notes
- Public clients only. Mobile and browser apps use PKCE S256 and have no client secret. Never ship a secret in an app.
- Store tokens in secure storage. Keystore or Keychain-backed storage (
expo-secure-storeon Expo). NeverAsyncStorage,localStorage, logs or crash reports. The stored blob holds the refresh token. - Use the system browser for sign-in (Custom Tabs,
ASWebAuthenticationSession,expo-web-browser), never an embedded WebView. - Check
stateon return and send a fresh randomnonceand PKCE verifier for every attempt. - Exact redirect URIs. https, loopback http, or a reverse-DNS custom scheme.
- Refresh tokens rotate. The SDK never retries a refresh and persists the new token before use. Do not run your own parallel refresh.
- Fail closed. A timeout never signs the person out, and never counts as success for a sensitive action.
- Pass the SDK a
fetchyou trust. Endpoints from discovery are rejected if they are not on the configured SeleID origin. - Telemetry is safe by construction but still send it only to your own logger.
- Report vulnerabilities through the security page.