README — DELETE /api/admin/sessions/{id}
DELETE /api/admin/sessions/{id}#
DELETE /api/admin/sessions/🆔 signs one session out. Your own: always. Another admin's: owners (admins.sessions)
with a fresh step-up. Revokes the session's Cognito refresh token too.Caller and authorization#
Staff cookie session; any admitted staff member. Write requests need same-origin JSON and X-Admin-CSRF from this session.This is the private staff console on https://admin.handwrites.io. A personal API key, organisation token, student login or isolated app-testing credential does not authenticate this route.Request contract#
| Location | Name | Required | Meaning |
|---|
| path | id | Yes | Use the ID from an authorized staff response; source validators reject malformed IDs. |
| header | X-Admin-CSRF | Yes | Session-bound token from the staff page; not a developer credential. |
This operation does not define a JSON payload. Staff writes still require Content-Type: application/json and the session-bound CSRF header.Response and failures#
Success: 204. Completed; no response body.The wrapper returns {error:{code,message}} for CloudError failures, attaches Request-Id, and disables caching. Handle 401 by signing in; show role refusal for 403 forbidden, reauthenticate only for step_up_required, and collect a reason for 400 reason_required. A CSRF failure needs a current page/session token, not blind retries. Operation-specific 404/409/413/422/502/503 errors retain their status. Honor Retry-After on 429.Usage notes#
Own-session revocation is permitted; revoking another staff member’s session additionally requires admins.sessions and fresh step-up.
Implementation contract#
Source snapshot: admin/src/app/api/admin/sessions/[id]/route.ts. This reference describes the current working tree, not proof of deployment. The response service types and validators remain authoritative. The exact exported handler below makes conditional behavior reviewable. For helpers such as customer-routes or cloudRoute, see the shared API specification notes and the named service module./**
* DELETE /api/admin/sessions/:id: signs one session out. Your own: always. Another admin's: owners (admins.sessions)
* with a fresh step-up. Revokes the session's Cognito refresh token too.
*/
export const DELETE = adminRoute(null, async (_request, ctx, { params }: Context, { session: current }) => {
const { id } = await params;
if (!/^[0-9a-f]{64}$/.test(id)) throw notFound("Session");
const target = await sessions.get(sessionPk(id), SESSION_SK);
if (!target) throw notFound("Session");
if (target.staffSub !== ctx.admin.sub) {
if (!can(ctx.admin.role, "admins.sessions")) throw new CloudError(403, "forbidden", "Your admin role doesn't allow this.");
if (!stepUpFresh(current)) throw stepUpRequired();
}
const revoked = await revokeSession(id, ctx.admin.sub);
await revokeRefreshToken(revoked?.cognitoRefreshToken);
await authAudit({ action: "admin.session.revoke", outcome: "ok", actorSub: ctx.admin.sub, role: ctx.admin.role, sessionId: ctx.sessionId, requestId: ctx.requestId, targetId: id, ip: ctx.ip, userAgent: ctx.userAgent });
const response = new NextResponse(null, { status: 204 });
if (id === ctx.sessionId) clearSessionCookie(response.cookies);
return response;
});
Do not use production customer data to test this operation. Use an authorized staff test account and a disposable target in an appropriate environment; email, deletion, role and credential mutations have real effects.Modified at 2026-10-26 13:41:16