Your Account¶
Everything under /who/me belongs to the caller: who they are, where they are signed in, their
passkeys, email addresses, linked provider accounts and API keys. Each endpoint checks ownership
itself, so an id that is not the caller's answers 404, exactly as an unknown id does, and an
application never has to write that check.
Each endpoint lives in the module that owns its data: passkeys in who-passkey, addresses in
who-email-link, accounts in who-oidc, keys in who-apikey. Adding the jar turns the endpoints
on, and the module's enabled=false turns them off with it.
The TypeScript client has a call for each one under who.me.
Who may call what¶
Three kinds of caller:
- Browser: a who browser session, with no API key or bearer token on the request. A session
cookie with an
X-API-KeyorAuthorization: Bearerheader beside it is not a browser, even when the header is ignored, so it is answered403BrowserSessionRequiredException(Who-Error: browser-session-required) wherever only a browser may act. Send the cookie alone. - Recent: a browser session signed in within
who.security.recent-sign-in(10 minutes by default). An older one gets401ReauthenticationRequiredException: sign the person in again and retry. who checks this before it looks at any id in the path, so a stale session learns nothing about what exists. - Signed in: any who sign-in, a browser session, a bearer token or an API key.
With the default who.base-path:
| Endpoint | Who may call | Recent sign-in | Success |
|---|---|---|---|
GET /who/me |
Signed in | no | 200 |
GET /who/sign-in |
Anyone, signed out included | no | 200 |
GET /who/me/sessions |
Browser | no | 200 |
DELETE /who/me/sessions/{id} |
Browser | only to end another session | 204 |
DELETE /who/me/sessions?others=true |
Browser | yes | 200 {"ended": 2} |
GET /who/me/passkeys |
Browser | no | 200 |
POST /who/me/passkeys/options, POST /who/me/passkeys |
Browser | yes | 200 |
DELETE /who/me/passkeys/{credentialId} |
Browser | yes | 204 |
GET /who/me/email-addresses |
Signed in | no | 200 |
POST /who/me/email-addresses |
Browser | yes | 202 |
POST /who/me/email-addresses/confirmations |
Browser | yes | 200 {"credentialId": "..."} |
DELETE /who/me/email-addresses/{id} |
Browser | yes | 204 |
GET /who/me/accounts |
Signed in | no | 200 |
POST /who/me/accounts/{registrationId} |
Browser | yes | a redirect to the provider, or 200 {"redirectUrl": "..."} |
DELETE /who/me/accounts/{id} |
Browser | yes | 204 |
GET /who/me/api-keys |
Browser or bearer token | no | 200 |
POST /who/me/api-keys |
Browser or bearer token | a browser only | 201 |
POST /who/me/api-keys/{id}/rotations |
Browser or bearer token | a browser only | 201 |
DELETE /who/me/api-keys/{id} |
Browser or bearer token | no | 204 |
GET /who/me/api-keys/current |
API key | no | 200 |
Every /who/me endpoint answers a signed-out request with 401 NotSignedInException. A
signed-in caller that is not one the table allows gets 403 BrowserSessionRequiredException
(browser-session-required), except that a request an API key signed in gets 403
ApiKeyCannotManageKeysException (api-key-cannot-manage-keys) at the API-key endpoints, since
a bearer token may manage keys too, and GET /who/me/api-keys/current answers 404 to a request
no API key signed in. Like every who failure, these are
answered as who's Problem Details, and every POST and DELETE from a browser
needs the CSRF header.
Which chains serve them:
GET /who/meanswers on every chain.GET /who/sign-in, the sessions and the passkey endpoints, and starting a link (POST /who/me/accounts/{registrationId}), are on chains that sign browsers in. A chain built withWhoSecurity.stateless()has none of them: there they are answered like any other path of yours.- The email-address, linked-account and API-key endpoints are on both kinds of chain, so a bearer
token or an API key on a stateless chain can list addresses and accounts, and a bearer token can
manage keys. What only a browser may do answers
403(browser-session-required) there.
Who is signed in¶
GET /who/me:
{
"identityId": "0f8e5c1a-6d1b-4e55-9a49-4c9f3a0a7d2e",
"permissions": ["task.read", "task.write"],
"signInMethod": "passkey",
"recentSignInUntil": "2026-11-17T10:22:44Z",
"credentials": { "email": 1, "passkey": 2, "account": 0 }
}
permissionsare the identity's current permissions; for an API key, those its scopes keep.signInMethodis how this request signed in, spelled as the sessions list spells it:email-link,email-code,passkey,oidc,api-keyorjwt. For a browser it is how its session signed in, andnullfor a session saved before who recorded that.recentSignInUntilis when the browser session's sign-in stops being recent. It may already have passed: compare it to the current time to decide whether to ask the person to sign in again before an action that needs it. It isnullfor anything but a browser session, since an API key or a bearer token stands for no sign-in.credentialscounts the identity's sign-in credentials by kind (email,passkey,account), for each sign-in module present;accountcounts only the linked accounts a configured provider registration signs in (see the last-credential rule). A page can use it to hide a Remove button on the last one. It is empty when who cannot count, which happens when there is no singlePlatformTransactionManager(see the last-credential rule).
What a sign-in page can offer¶
GET /who/sign-in is public and says nothing about any identity. It tells a signed-out page which
buttons to draw:
{ "email": true, "passkey": true, "providers": [{ "id": "github", "name": "GitHub" }] }
email and passkey are false when their module is absent or turned off. providers lists the
provider registrations who signs in with, in the order they are configured; id
is the registration id, which GET /who/oidc/authorize/{id} takes, and name is the
registration's client-name (Spring uses the id when none is set). who's default chain opens it to
signed-out requests, and it is in WhoPublicPaths for a chain of your own.
Sessions¶
GET /who/me/sessions, DELETE /who/me/sessions/{id} and DELETE /who/me/sessions?others=true:
see Sessions.
Passkeys¶
GET /who/me/passkeys lists the caller's passkeys, oldest first:
[{ "credentialId": "q3JzT1...", "label": "Laptop", "createdAt": "2026-11-16T09:12:44Z", "lastUsedAt": "2026-11-17T08:00:01Z" }]
credentialId is the WebAuthn credential id in base64url, which names the passkey in
DELETE /who/me/passkeys/{credentialId}. who's internal id is not shown. lastUsedAt is null for
a passkey that has never signed in.
Registering one is POST /who/me/passkeys/options and then POST /who/me/passkeys; see
Passkeys. Removing the passkey a session signed in with ends that
session.
Email addresses¶
GET /who/me/email-addresses lists the caller's addresses, oldest first:
[{ "id": "0193f2a4-...", "address": "alice@example.com", "createdAt": "2026-11-16T09:12:44Z" }]
id is the email credential's id: DELETE /who/me/email-addresses/{id} takes it, and so does
replaces when changing an address. createdAt is read from the id, which records when it was made.
Adding or changing an address (POST /who/me/email-addresses, then
POST /who/me/email-addresses/confirmations) is in
Email Links.
Removing the address a session signed in with is allowed. That session ends, as with any revoked
credential: its next request is 401, and the person signs in with another credential.
Linked accounts¶
GET /who/me/accounts lists the provider accounts linked to the caller, oldest first:
[{ "id": "0193f2a4-...", "provider": "github", "linkedAt": "2026-11-16T09:12:44Z" }]
provider is the registration id whose issuer matches the account's, or the issuer itself when no
registration matches any more. A JWT (issuer, subject) linked to the identity is listed too, with
its issuer. linkedAt is read from the id.
POST /who/me/accounts/{registrationId} starts a link; see
Social Login.
DELETE /who/me/accounts/{id} unlinks one. Unlinking the account a session signed in with ends
that session.
API keys¶
A browser session or a bearer token may manage the caller's keys. A request an API key signed in
gets 403 api-key-cannot-manage-keys on all of them but /current: a key never lists, makes, rotates or revokes keys, so a
leaked key cannot make itself permanent.
| Request | Body | Answer |
|---|---|---|
GET /who/me/api-keys |
200 [{id, name, scopes, createdAt, expiresAt, lastUsedAt}], by name |
|
POST /who/me/api-keys |
{"name": "CI", "lifetime": "P90D", "scopes": ["report.read"]} |
201 {id, name, scopes, expiresAt, key} |
POST /who/me/api-keys/{id}/rotations |
{"overlap": "PT1H"} |
201 {id, name, scopes, expiresAt, key}, the new key |
DELETE /who/me/api-keys/{id} |
204 |
|
GET /who/me/api-keys/current |
200 {id, name, scopes, createdAt, expiresAt, lastUsedAt}, the key that signed this request in |
key, the secret, is in the two201answers and nowhere else: not in the list, not in/current, not in a log line. Show it to the person once.lifetimeandoverlapare ISO-8601 durations.overlapis required; the old key keeps working for that long. The limits are those ofApiKeyService: the lifetime at mostwho.api-key.max-lifetime, the overlap at most 7 days, and only scopes the owner holds.lastUsedAtisnullfor a key never used, and lags by up towho.api-key.last-used-interval.- A browser needs a recent sign-in to make or rotate a key. A bearer token does not: its own lifetime bounds it.
/currenttakes the key from the sign-in, never from the request, so a machine can read its own expiry and nothing else. Without an API key it is404.- An id that is not one of the caller's keys, unknown or malformed, is
404(ApiKeyNotFoundException). A body who refuses (not JSON, a missing field, a duration it cannot read or that is out of range, a blank name, no scopes or a scope the owner lacks, or a key that expired or was revoked before its rotation) is400(InvalidApiKeyRequestException).
The last-credential rule¶
Removing a passkey, an email address or a linked account through /who/me answers 409
LastCredentialException (Who-Error: last-credential) when it would leave the identity with no
way to sign in. Email addresses, passkeys and linked accounts count; API keys do not, because they
sign in a machine, not the person.
The count and the removal happen in one transaction that locks the identity's row
(SELECT ... FOR UPDATE), so two removals at once cannot both pass the check. The order of checks
on a removal is: signed out (401), not a browser (403), not recent (401), not the caller's
(404), the last credential (409).
Only a linked account that a configured provider registration signs in counts: one whose
issuer is the issuer of a registration who signs in with today. An account
whose provider was removed from the configuration, and an (issuer, subject) a JWT
signs in with, are not counted, since no one can sign in with them at /who/oidc; without
who-oidc, or with who.oidc.enabled=false, no linked account counts. Unlinking such an account
is never refused: it cannot be the last way in. Email addresses and passkeys count whenever their
module is on.
The services keep their contract: PasskeyService.revoke, EmailCredentialService.revoke and
FederatedCredentialService.unlink check neither ownership nor this rule. Code of yours that
removes a credential on a person's behalf applies the rule with the LastCredentialGuard bean:
guard.removeIfNotLast(identityId, () -> {
passkeyService.revoke(passkeyId);
return null;
});
The guard needs who-jdbc and exactly one PlatformTransactionManager bean (Spring Boot makes one
for a single DataSource). who-passkey, who-email-link and who-oidc need the guard, so with
any of them on, an application without a single transaction manager fails startup with
NoSuchBeanDefinitionException for LastCredentialGuard. Name one manager @Primary, or define
your own LastCredentialGuard bean.
Call removeIfNotLast outside any transaction of yours. It runs the count and the removal in a
READ COMMITTED transaction whatever the database's default, so a removal that waited for the lock
counts what the other committed; inside a transaction of yours it joins yours, at your
transaction's isolation, and under REPEATABLE READ two removals could both pass. See
Transactions and locks.