On-site: issuing & countersigning

For Authorised issuer (appointed person)

Your role

You are the appointed person who makes a permit live at the workface. Once an approved permit reaches the morning walk-down, you are the person who physically inspects the area, verifies that the controls written into the permit are actually in place, and signs it off. Critically, you hold this power because someone in the H&S band has given you a PermitAppointment — not because of your site role. A member, coordinator, HSE manager, or admin can all be appointed; equally, being a coordinator or admin does not let you issue unless you also hold an appointment. Your appointment can be scoped to a single permit type (e.g. Hot Works only) or to all types. Your signature at /issue records that the walk-down happened — but the permit does not actually go live until the named receiver countersigns. You also have the authority to refuse a permit at the workface if the controls aren't right, and to perform close-out when the work is done.

What you can and can't do

You can

• Issue an approved permit by signing the walk-down (POST .../issue) — for the permit type(s) you are appointed for.
• Refuse at the walk-down: reject (.../reject) or request corrections (.../request-corrections) on an approved permit when controls aren't in place — at the approved stage, the appointed issuer is the acting gate.
• Close out an issued or expired permit (.../close-out) via the appointed-issuer path, taking it to closed.

You can't

• Make a permit live by yourself. /issue only records your signature and leaves the status at approved ("awaiting countersign"). Only the named receiver's countersign flips it to issued.
• Sign twice. Issue refuses a second issuer signature; countersign refuses if no issue signature exists yet. The order is enforced.
• Issue for a type you aren't appointed for. A type-scoped appointment matches only its type; an all-types appointment (null type) matches everything. Otherwise issue is refused with "Issuing requires an authorised-issuer appointment."
• Endorse or approve — those are the coordinator (stage-1) and HSE/admin (stage-2) desk gates. Your appointment grants only issuing and close-out, not the desk gates, unless you also hold the relevant role band.
• Close out a parent permit while it still has open child permits. The close-out is blocked and the system lists the blocking child permit numbers.

Note: Your appointment is created and revoked by the HSE/admin band (under Permit settings → Authorised issuers). If your appointment is revoked, can_issue simply stops being true on your permits — you won't get an error in advance, the Issue affordance just won't appear. Revoked appointments are retained for audit.

Your tasks

Task 1 — Issue a permit at the walk-down (sign it)

This is the core ceremony. An approved permit is "approved for tomorrow, not yet live" until you walk the area and sign.

1. Pick up the work. When a permit is approved, you (as an appointed issuer for that type) receive an issue_permit Task. Open the My Work dock panel (the Tasks tab) and find the card labelled "Issue (walk-down)". Tapping it deep-links you to the walk-down route /permits/{id}/issue. (You can also reach this route directly from the link in the "Permit {number} ready to issue" notification.)
2. The walk-down screen. The route is phone-first and shell-free — it works on a handset at the workface, behind a normal Keycloak login. The header shows the permit's type glyph, status wash, and work window. Below it is the "Verify before issue" checklist, built from the permit's conditions of issue (the structured controls plus any free-text controls added at endorsement, approval, or issue). If the permit carries no conditions, you'll see a single fallback item: "Walk-down complete — area inspected and safe to start work."
3. Physically verify, then tick. Walk the area. Confirm each control is genuinely in place, then tick its checkbox. A counter shows your progress (e.g. "3/5"). There is an optional issue note field for anything you want recorded.
4. Sign. The sticky "Sign & issue" button is disabled until can_issue is true and every checklist item is ticked (the hint reads "Tick all checks to enable signing"). Press it.
5. What the system does. This calls POST /api/permits/applications/{id}/issue with action=issue. It records your issue signature (with a SHA-256 content hash of the permit as signed, your name, and the timestamp), fires a permit_awaiting_countersign notification to the named receiver, and leaves the status at approved. The board and detail now show a derived "awaiting countersign" flag.
6. The receiver finishes it. The named receiver opens their own countersign route (/permits/{id}/countersign), accepts the conditions, and countersigns — that is the action that flips the permit to issued (live), emits permit_issued, and freezes the PDF to S3. You do not need to do anything further for go-live.

Note: If you see the walk-down screen in a calm, read-only state (e.g. "Signed at the walk-down — awaiting the receiver's countersign."), it means can_issue is false — usually because your signature is already on the permit and it's now the receiver's turn. This is expected, not an error.

Task 2 — Refuse at the workface (controls not in place)

If you arrive and the controls aren't right, do not sign. At the approved stage you are the acting gate, so you can bounce the permit.

1. From the permit (the walk-down screen or the Permits panel detail), choose to reject or request corrections rather than signing.
2. Reject (POST .../reject) is a terminal refusal — the permit moves to rejected and cannot re-enter the chain. A note/reason is required.
3. Request corrections (POST .../request-corrections) bounces the permit back to the requestor as editable — it moves to corrections_requested. A note is required; the requestor fixes it and resubmits, which restarts the approval chain at requested.
4. In both cases the requestor and receiver are notified (the reject/corrections note rides the notification body), and any open gate Tasks on the permit are auto-closed.

Note: Choose request corrections (recoverable) rather than reject (terminal) when the problem is fixable — e.g. a missing fire watch or an out-of-date RAMS reference. Reject is for permits that should not have reached the walk-down at all.

Task 3 — Close out a permit on completion

When the work is finished (or a permit has expired and needs formally ending), close it out.

1. Open the Permits dock panel (keyboard P). Find the permit — live permits sit under "Live", overdue ones under "Expired — unclosed" (a loud red section).
2. Select it and open the close-out surface (the detail footer's close-out action, or pick up a "Close out" Task from My Work if one was raised on expiry).
3. Work through the fixed 3-item safety checklist:
   • Work complete and all tools / plant removed
   • Work area made safe, clean and checked
   • Fire watch held to completion (where required)
4. There's an optional close-out note. The "Sign & close out" button stays disabled until all three are confirmed (hint: "Confirm all checks to sign").
5. Press "Sign & close out". This calls POST .../close-out, records a close_out signature, optimistically flips the permit to closed, and re-snapshots the PDF.

Note: Close-out keys on the permit's state, not the calendar — both issued and expired permits are closed out the same way. An expired permit is an alarm state, not a finished one: it still needs your close-out sign-off to reach closed. The scheduler will never close a permit for you.

Note: If the permit is a parent with open (non-terminal) children, close-out is blocked and the rejection names the blocking child permit numbers inline. Close those children first, then close the parent.

What you'll be notified about

Trigger	What you get	Where it lands
A permit you can issue is approved (permit_approved)	issue_permit Task "Issue (walk-down)" + a "Permit {number} ready to issue" notification	My Work card (deep-links to /permits/{id}/issue); bell
A live permit you issued is nearing its end (permit_expiring_soon)	"Permit {number} is expiring soon" notification + email (you receive this as the user on the issue signature)	Bell + email

Note: Your issue_permit Task is auto-resolved once the permit goes live (permit_issued) — you don't manually clear it. If the permit is rejected, corrections are requested, or it's withdrawn, all open gate Tasks on it (including yours) are closed automatically, so you won't be left holding a stale walk-down task. The expiring-soon ping is computed against the site's expiring-warning lead (default 24h, set by HSE/admin in Permit settings → Policy) and fires exactly once per permit — don't expect a repeating reminder.

Gotchas

• The appointment, not your role, grants issuing. Even a site admin or superadmin cannot issue without an active PermitAppointment — is_appointed_issuer has no superadmin shortcut. Conversely, a plain member who holds an appointment can issue. Check that your appointment exists (and covers the permit's type) if the "Sign & issue" button never enables.
• Your signature is not go-live. This is the single most common misunderstanding. /issue records your walk-down signature and stops at approved (awaiting countersign). The permit only becomes issued/live when the named receiver countersigns from their own device. If work hasn't started, check whether the receiver has countersigned yet — that's usually the missing step.
• Type scoping is real. If your appointment is for a specific type (say WAH — Working at Height) you can only issue WAH permits. A Hot Works permit will refuse your signature with "Issuing requires an authorised-issuer appointment." Ask HSE/admin to widen your appointment (or appoint someone for the other type).
• The close-out gate is a separate thing from your close-out action. If the site has close_out_gate_enabled turned on, a contractor with expired-unclosed permits is blocked from having new permits issued — and that block fires at your /issue moment, naming the blocking permit numbers. The fix is to close out those expired permits (yours or a colleague's) first. Approvals still proceed; only the issue/walk-down step is gated.
• Refusing is a workface authority, not a role. You can reject or request corrections at the approved stage because you're the appointed issuer standing at the gate — but you cannot endorse (stage-1) or approve (stage-2) from the appointment alone. Those remain coordinator and HSE/admin desk decisions.

For Named receiver / field signatory

Your role

You are the named receiver on a permit — the member of the receiving contractor who actually takes the permit live. By default the receiver is the permit's requestor, but it can be any named member (permit.receiver_id). After the appointed issuer has signed the walk-down, the permit sits in approved ("awaiting countersign") until you countersign from your own session. Your countersignature is the single action that flips the permit to issued (live) and authorises work to start — it emits permit_issued and freezes the permit PDF. This is identity-gated, not role-gated: you can hold any site role (viewer through admin, even superadmin), but only the person named as receiver on that permit may countersign it.

What you can and can't do

You can

• Countersign a permit where you are the named receiver (POST .../countersign) — this flips the status to issued, emits permit_issued, and freezes the PDF.
• Accept the conditions of issue on the responsive countersign screen (/permits/:id/countersign).
• Receive a permit_awaiting_countersign notification that deep-links you to the signing screen.

You can't (from this role alone)

• Countersign before an issue signature exists — the system refuses (you can only countersign a permit the appointed issuer has already signed).
• Countersign someone else's permit — only permit.receiver_id may countersign; any other user gets a PermitGateError (403), regardless of role, including a site admin or superadmin who is not the named receiver.
• Issue / endorse / approve the permit — issuing needs an authorised-issuer appointment; endorse/approve need the coordinator or H&S role bands. Being the receiver grants you the countersign and nothing else on the lifecycle.

Note: Countersigning is purely about who you are on this permit, not your seniority. A superadmin who is not the named receiver cannot countersign; a viewer-level member who is the named receiver can. There is no override.

Your tasks

Task 1 — Reach the countersign screen

You get to the countersign screen one of two ways. Note that countersign is not a Task — it will not appear as a card in the My Work panel (only the issuer's walk-down step gets a Task card). You arrive from the notification or the direct URL.

1. When the appointed issuer signs the walk-down, the system fires a permit_awaiting_countersign notification to you (the named receiver). It appears in your in-app notification bell and, where SMTP is configured, by email.
2. Open the notification. The countersign screen lives at the route /permits/{id}/countersign — reach it from the notification's link or the URL directly.
3. The countersign screen is phone-first (designed for use at the workface on a handset) and uses the normal Keycloak login — no special app. If you are not signed in, you will be prompted to log in as yourself first.

Note: Clicking the notification in the in-app list currently does not auto-open the permit screen for you — the in-app notification router has no permit case yet, so a permit notification is informational but does not deep-link. Use the link in the email, or navigate to /permits/{id}/countersign directly. (Permit Tasks — the issuer's walk-down card — do deep-link correctly; the countersign notification does not.)

Task 2 — Read the conditions, accept, and countersign to go live

1. On the /permits/{id}/countersign screen you'll see the permit's field header (type glyph, status wash/label, work window) and the read-only "Conditions of issue" list. These conditions are assembled from the permit's controls plus anything the reviewers and issuer added at endorsement, approval, and issue — read them; they are what you are agreeing to work under.
2. Tick the "I accept these conditions" checkbox. The "Countersign & start work" button (clipboard-document-check glyph) stays disabled until both the checkbox is ticked and can_countersign is true for you (i.e. an issue signature already exists and you are the named receiver).
3. Press "Countersign & start work." This calls POST /api/permits/applications/{id}/countersign with action=countersign.
4. The system records your countersignature (append-only, with a content hash and your name snapshot), flips the permit status from approved → issued, emits permit_issued, and freezes the permit PDF to storage. The permit is now live: it goes site-public on the board, work is authorised, and the requestor + receiver are notified that the permit is now live.

Note: Both signatures are required and order is enforced. The appointed issuer signs first (/issue) — that records their signature but leaves the permit at approved. Your countersign is what actually goes live. If you reach the screen and the button is greyed out with no issue signature yet, the issuer hasn't completed the walk-down — wait for them.

What you'll be notified about

Trigger	What you get	Where it points
Issuer signs the walk-down (permit_awaiting_countersign)	In-app notification + email — "ready to countersign"	/permits/{id}/countersign (via the email link / direct URL)
Permit goes live (permit_issued)	In-app + email — "Permit {number} is now live", to requestor + receiver	informational
Permit rejected (permit_rejected)	In-app + email with the rejection reason, to requestor + receiver	informational
Corrections requested (permit_corrections_requested)	In-app + email with the reviewer's note, to requestor + receiver	informational
Permit expires unclosed (permit_expired)	A close_out_permit Task to requestor + receiver ("Close out expired permit {number}")	the close-out surface
Extension approved / rejected	In-app notification, to requestor + receiver	informational

Note: The awaiting-countersign signal is deliberately a notification, not a Task — it represents a workface signature, not a desk gate, so it does not appear in My Work. Don't go looking for it there; look in your notifications/email.

Gotchas

Note: The countersign is the go-live, not the issue. Many people assume "issued" happens when the issuer signs. It does not — POST /issue only records the issuer's signature and leaves the permit at approved (an "awaiting countersign" derived flag, not a real status). Your countersign is the only thing that flips it to issued. Until you sign, no work is authorised.

Note: You must be the named receiver. The receiver defaults to the requestor, but on permits where someone else is named, only that person can countersign — the gate keys on permit.receiver_id, with no role bypass. If you believe you should be the receiver but the button is disabled (and you're logged in as yourself with an issue signature present), the permit is probably named to someone else; the requestor/coordinator needs to correct the receiver.

Note: You can't countersign early. If no issue signature exists yet, the countersign call is refused. The conditions-of-issue list and the disabled button are the tell — wait for the appointed issuer to finish the walk-down.

Note: Sign from your own session on your own device. The countersign is an authenticated identity action (your login + timestamp + content hash become part of the permit's audit chain and render onto the PDF). Don't sign on someone else's logged-in session — it records the wrong signatory.

---

Permits guide: Overview · Applying · Reviewing & approving · On-site signing · Configuring · Reference