Device grants
A device grant (「设备授权」) is the only thing that lets a controller device connect to a host in FortSwift. There is no shared password, and no "know the ID and you are in" — every access corresponds to a named record with an expiry date that can be revoked.
The daily path
Controller submits a request → Owner/admin approves with the account code → Takes effect (at most about 60 seconds)The approver is not necessarily the requester
The request is raised by the person using that device, but approval must be done by the tenant's account owner or an administrator. If you are not one of those, you submit the request and wait for them — you cannot approve your own.
Grant states
A request moves through these states:
| State | Meaning |
|---|---|
| Not requested (未申请) | This device has never submitted one |
| Pending (待批准) | Submitted, waiting for an owner/admin (already books a quota slot) |
| Awaiting issuance (等待签发) | Approved, being issued and delivered |
| Authorized (已授权) | In effect, you can connect (with an expiry date) |
| Rejected / Expired (已拒绝 / 已过期) | You can request again |
| Revoked (已撤销) | The same key cannot simply request again |
Step 1: Request from the client
In the client, open Trust Center → Device grants · remote control permission (「设备授权 · 远控权限」) and click Request remote control permission (「申请远控权限」).
The client signs a one-time challenge with the local controller key to prove it really holds that key, then submits the request. The private key never leaves the device.
TIP
A request books a grant slot the moment it is submitted. Repeatedly requesting without anyone acting on it is a good way to hit quota exceeded. Rejecting a pending request frees its slot immediately.
A device that already holds a grant no longer shows the request entry point.
Step 2: Approve with the account code
Approval works from either place, with the same result:
- The portal → the Device grants (「设备授权」) page, which has Pending / Authorized / History sections;
- In the client, on the same screen — if the signed-in account is itself the owner or an administrator, you can type the code and approve right there.
What you enter is the account code (TOTP) — the 6-digit code in your authenticator app.
Do not reach for the wrong credential
This wants the account code, not the keymachine operator code. They are different credentials, and using one for the other always fails.
The code exists in memory only for that submission, is cleared straight after, and is never written to storage.
Why you re-enter it every time
Any operation that changes authorization state (approve, reject, revoke) requires FortSwift to re-verify the code on the spot. Having verified it at sign-in does not count — this is what stops someone granting themselves access while your machine is unlocked and unattended.
Step 3: Wait for it to take effect
After approval the grant has to be issued and delivered before it is usable. Hosts sync their trust state about every 30 seconds, so it takes effect at most about 60 seconds later.
On a successful approval you will see one of:
- "Approved and issued, takes effect on the host within about 60 seconds" — done;
- "Approved and delivered to the signing service, awaiting issuance confirmation" — delivered, waiting for confirmation.
Validity period
30 days by default, configurable, with a 90-day ceiling.
It lapses on expiry with no manual clean-up, and the slot is freed with it. To keep access, request again.
The portal is authoritative
The effective validity for your service is set by configuration. For the exact expiry date, the Device grants page in the portal is authoritative.
Why grants expire at all
Permissions should expire by default rather than persist by default. Staff turnover, replaced machines, short-term collaboration — the thing that goes wrong in all of them is the access someone opened years ago that nobody ever took back.
Revoking
Revocation is portal-only — on the Device grants page, in the Authorized list, click Revoke. It needs the account code and, again, owner/admin role. There is no revoke entry point in the client.
Revocation takes effect once the signer confirms it. The host loses the grant on its next trust sync (at most about 60 seconds), and the slot is freed at the same time.
After revocation the same key cannot request again
This is deliberate. If you revoked something by mistake, contact the account owner — you cannot simply resubmit.
Revoking does not kick a session that is already running
Revocation blocks subsequent connections. If someone is connected right now, confirm separately that the session has ended.
Grant slots
Your grant ceiling is set by your plan. What counts:
- Occupies a slot: pending requests, authorized grants;
- Does not occupy a slot: rejected, expired, revoked.
Slots are counted across the whole account tree — what a sub-account uses counts against its parents too, so a sub-account can never exceed the tenant ceiling.
When you run out you see "device grant quota exceeded"; see troubleshooting.
How this differs from controller governance
The two get confused often, but they use different credentials and solve different problems:
| Device grants | Controller governance | |
|---|---|---|
| Question it answers | "Can this computer do remote control?" | "Which controllers are in the account's governance set?" |
| Credential | Account code (TOTP) | Keymachine operator code + owner's account code |
| Portal page | Device grants (「设备授权」) | Governance controller approvals (「治理控制端授权」) |
| Frequency | Daily, often | Rarely |
| Slots | Its own device-grant quota | Bounded by the quorum ceiling, does not consume device-grant slots |
Day-to-day use only ever touches the left-hand column.
Next
- The target machine is not ready yet → enabling a host
- Hit an error → troubleshooting
- Where this lives in the portal → portal guide