Concepts
Core mental models for building on Avnology ID.
Concepts
Pick these up before you pick a quickstart. They frame the decisions that shape the rest of your integration.
Decisions
- Hosted vs embedded -- should users sign in on
id.avnology.net/sign-in?client_id=...or inside your app via<SignIn/>? - B2B vs consumer -- how organizations work and whether you need them.
Core model
At its core, Avnology ID has four entities that show up everywhere:
| Entity | Aka | Identifier |
|---|---|---|
| Identity | User, account | usr_... |
| Session | Login instance | ses_... (Bearer: avnl_ses_...) |
| Organization | Tenant, workspace | org_... |
| Permission tuple | Role grant | (namespace, object, relation, subject) |
An identity can belong to zero, one, or many organizations. A session is always scoped to one identity; the same session can be elevated (step-up) to act on behalf of a specific organization. Permissions live in Keto (our authz engine, wrapped in the PermissionService) and are tuples the gateway checks on every request.
Flows
Authentication in Avnology ID is always a flow: a state machine your frontend walks through by rendering UI nodes the server returns. You don't embed form HTML; you read the nodes out of the flow object and render them. This is what makes login / registration / recovery / MFA all look and behave consistently, and what powers the hosted Universal Login UI.
See Auth flows for the API surface.
Tokens
Three kinds:
- Session tokens --
avnl_ses_..., sent as Bearer, used between your frontend and the gateway. Short-lived (15 min default) with refresh rotation. - Access tokens (OAuth) -- standard JWTs, used between your backend and third-party APIs you've federated to. PKCE + DPoP supported.
- API keys -- long-lived, scoped to a service account, used server-to-server. Prefixed
ak_live_.../ak_test_....
Never put any of these in URLs.
Next
Once you've framed the integration:
- Quickstart -- five-minute setup for a framework of your choice.
- SDKs -- pick TypeScript, Go, or Python.
- Components -- prebuilt React UI.