# Sign-in and identity

Identity is how Jadpo knows who is calling. You say which of your stored
records is a person and which is another system, and which ways in your
app accepts, such as a browser session or an API token. Jadpo checks the
caller on every request and gives your code one typed value for them,
`current_principal`. What that caller may do is decided separately, by
[Policy](/docs/policy.md).

You write it in three places, and read the caller in a fourth:

| Piece | Where | What it says |
|---|---|---|
| `principal { }` | `app.jadpo` | Which entity is a user, which is a service, and when each is active |
| `authentication { }` | `authentication.jadpo` | The ways a caller can sign in, and with `sign_in:` how a person is checked |
| `application { }` | `app.jadpo` | How long a revoked session may keep working, and the app's name in emails |
| `current_principal` | routes | The signed-in caller, passed to actions |

Five rules hold underneath all of it:

- Every route needs a signed-in caller unless it says otherwise.
- A request carries exactly one credential. A request with two, or with an
  invalid one beside a valid one, is refused; Jadpo never picks one.
- Jadpo checks the caller before it reads the request body or runs any of
  your code.
- Your code gets one typed caller. It never sees cookies, tokens, keys or a
  provider's claims.
- A credential never holds permissions. Policy decides them.

People sign in with a [magic link](/docs/magic-links.md) sent by email, or with a
[passkey](/docs/passkeys.md). An app can also accept tokens from an identity
provider it already uses ([Ways to sign in](/docs/ways-to-sign-in.md)). Jadpo has
no password sign-in.

| Page | What it covers |
|---|---|
| [The principal](/docs/the-principal.md) | The principal is whoever is calling, once Jadpo has checked them: either a user (a person) or a service (another system, such as a partner's server). |
| [Who is calling: current_principal](/docs/who-is-calling-current-principal.md) | A route reads the signed-in caller as `current_principal`, and passes it to the action it runs like any other argument. |
| [Ways to sign in](/docs/ways-to-sign-in.md) | `authentication { }` in `authentication.jadpo` lists the ways your app lets a caller prove who they are. |
| [Checking the person: sign_in.](/docs/checking-the-person-sign-in.md) | Signing in has two steps. |
| [Magic links](/docs/magic-links.md) | A magic link signs a person in by email, with no password. |
| [Passkeys](/docs/passkeys.md) | A passkey lets a person sign in with their fingerprint, their face or their device's PIN, with no password and no email to wait for. |
| [A person the app has not seen](/docs/a-person-the-app-has-not-seen.md) | The first time someone signs in whom your app has no user for, Jadpo asks your app what to do. |
| [Signing in from code the app writes](/docs/signing-in-from-code-the-app-writes.md) | Most apps let `sign_in:` check people. |
| [Routes: signed in by default](/docs/routes-signed-in-by-default.md) | Every route needs a signed-in caller unless it says otherwise. |
| [Starting and ending a session](/docs/starting-and-ending-a-session.md) | Magic links, passkeys and providers start the session themselves (Checking the person). |
| [Service credentials](/docs/service-credentials.md) | A service, such as a partner's system or a worker, signs in with a key. |
| [The application and revocation](/docs/the-application-and-revocation.md) | A person can be disabled, or a session revoked, while they still hold a valid cookie or token. |
| [Sign-in in development and tests](/docs/in-development-and-tests.md) | In `jadpo dev`, no email leaves your machine. |
| [Sign-in events](/docs/sign-in-events.md) | Every sign-in publishes a built-in event, which your monitoring and your app's own subscribers can use. |
| [Sign-in failures](/docs/identity-failures.md) | Jadpo raises the sign-in failures itself. |

[What is built](/docs/identity-built.md) says which of this works today.

## Details

The exact rules, for when you hit an edge case.

| Page | What it covers |
|---|---|
| [What the compiler checks of sign-in](/docs/what-the-compiler-checks-of-sign-in.md) | Jadpo checks your sign-in setup when it compiles, so a mistake is an error with a fix rather than a sign-in that fails in production. |