POST /v1/auth/logout

Revoke the current session and clear session cookies.

::: tip Auth Optional. Behaviour adapts:

• If the caller is authenticated, the entire session family is revoked.
• If only the refresh cookie is present, that specific session is revoked.
• If neither is present, cookies are still cleared and 204 is returned. :::

Request

POST /v1/auth/logout

Header	Required	Notes
Cookie: identsphere_at=... OR Authorization: Bearer ...	no	If present, the auth middleware identifies the session family.
Cookie: identsphere_rt=...	no	If present without auth, used as the revocation key.
X-CSRF-Token	yes (cookie auth)	Standard CSRF requirement.

No request body.

Response

204 No Content

Cookies cleared:

• identsphere_at — set to empty, Max-Age=0
• identsphere_rt — set to empty, Max-Age=0
• identsphere_csrf — set to empty, Max-Age=0

The identsphere_trust cookie is NOT cleared by logout; trusted-browser status persists across sessions. To remove it use DELETE /v1/auth/trusted-browsers/:id.

Error responses

Status	Code	When
500	internal_error	Database failure during revocation.

Logout never fails on missing or invalid auth — cookies are always cleared.

Example: curl

curl -X POST https://auth.example.com/v1/auth/logout \
  -b cookies.txt \
  -c cookies.txt \
  -H "X-CSRF-Token: $(grep identsphere_csrf cookies.txt | awk '{print $7}')"

Example: TypeScript (@identsphere/react)

import { useLogout } from '@identsphere/react';

function LogoutButton() {
  const logout = useLogout();
  return (
    <button onClick={() => logout.mutateAsync().then(() => navigate('/login'))}>
      Sign out
    </button>
  );
}

Notes

• Logout is idempotent. Calling it twice has the same effect as calling it once.
• The audit entry (auth.logout) is only recorded when an authenticated caller is present — refresh-cookie-only logout is silent in audit.
• The session-cache entry for the revoked family is invalidated so the next request that presents the old access token sees the revocation immediately.