Approving Registrations
Review, verify, and approve pending client registrations.
Approval Workflow
Section titled “Approval Workflow”Pending Registration Queue
Section titled “Pending Registration Queue”New agent registrations appear in the pending queue:
┌─────────────────────────────────────────────────────────────┐│ Pending Registrations (5) │├─────────────────────────────────────────────────────────────┤│ ││ ┌────────────────┬────────────────┬─────────┬───────────┐ ││ │ Client │ IP Address │ Age │ Actions │ ││ ├────────────────┼────────────────┼─────────┼───────────┤ ││ │ web-prod-01 │ 192.168.1.100 │ 5 min │ [···] │ ││ │ web-prod-02 │ 192.168.1.101 │ 3 min │ [···] │ ││ │ api-prod-01 │ 192.168.1.110 │ 1 min │ [···] │ ││ │ unknown-01 │ 10.0.0.50 │ 30 min │ [···] │ ││ │ test-server │ 172.16.0.25 │ 2 hrs │ [···] │ ││ └────────────────┴────────────────┴─────────┴───────────┘ ││ ││ [Approve All] [Reject All Stale] ││ │└─────────────────────────────────────────────────────────────┘Review Registration Details
Section titled “Review Registration Details”Before approving, review the registration details:
┌─────────────────────────────────────────────────────────────┐│ Review Registration │├─────────────────────────────────────────────────────────────┤│ ││ Status: ○ Pending Approval ││ ││ ───────────────────────────────────────────────────────── ││ ││ Client Details: ││ ┌───────────────────────────────────────────────────────┐ ││ │ Name: web-prod-01 │ ││ │ Hostname: web-prod-01.example.com │ ││ │ IP Address: 192.168.1.100 │ ││ │ Machine ID: 550e8400-e29b-41d4-a716... │ ││ │ Registered: 5 minutes ago │ ││ └───────────────────────────────────────────────────────┘ ││ ││ Certificate Thumbprint: ││ ┌───────────────────────────────────────────────────────┐ ││ │ AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90: │ ││ │ 12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF │ ││ │ │ ││ │ [Copy] [View Certificate] │ ││ └───────────────────────────────────────────────────────┘ ││ ││ Verification Checklist: ││ ☐ Hostname matches expected server ││ ☐ IP address is from known network ││ ☐ Registration timing is expected ││ ☐ Thumbprint verified (if pre-registered) ││ ││ [Reject] [Request Info] [Approve] ││ │└─────────────────────────────────────────────────────────────┘Approving via Lens UI
Section titled “Approving via Lens UI”Single Approval
Section titled “Single Approval”- Navigate to Registrations in Lens
- Find the pending registration
- Click to view details
- Verify client information
- Click Approve
┌─────────────────────────────────────────────────────────────┐│ Approve Registration │├─────────────────────────────────────────────────────────────┤│ ││ You are approving: ││ Client: web-prod-01 ││ Thumbprint: ABCDEF1234... ││ ││ Assign to Tenant (optional): ││ [Acme Corp ▼] ││ ││ Notes: ││ [Verified via infrastructure team ticket OPS-1234 ] ││ ││ ┌───────────────────────────────────────────────────────┐ ││ │ ⚠ Once approved, this client can receive deployments.│ ││ └───────────────────────────────────────────────────────┘ ││ ││ [Cancel] [Approve] ││ │└─────────────────────────────────────────────────────────────┘Bulk Approval
Section titled “Bulk Approval”For multiple registrations from a trusted source:
┌─────────────────────────────────────────────────────────────┐│ Bulk Approve Registrations │├─────────────────────────────────────────────────────────────┤│ ││ Selected: 3 registrations ││ ││ ☑ web-prod-01 192.168.1.100 5 min ago ││ ☑ web-prod-02 192.168.1.101 3 min ago ││ ☑ api-prod-01 192.168.1.110 1 min ago ││ ││ Assign to Tenant: ││ [Acme Corp ▼] ││ ││ Notes: ││ [Bulk approval for new production cluster ] ││ ││ [Cancel] [Approve Selected] ││ │└─────────────────────────────────────────────────────────────┘Approving via CLI
Section titled “Approving via CLI”Single Approval
Section titled “Single Approval”Client certificate registrations are approved with mantisctl cert.
# Approve by registration ID (or thumbprint prefix)mantisctl cert approve 550e8400-e29b-41d4-a716-446655440000
# Approve with notesmantisctl cert approve 550e8400-e29b-41d4-a716-446655440000 \ --notes "Verified via ticket OPS-1234"Bulk Approval
Section titled “Bulk Approval”# Approve all pending registrations from a specific IP rangemantisctl cert list --status pending --verbose | \ grep "192.168.1." | awk '{print $1}' | \ xargs -I {} mantisctl cert approve {}Verification Steps
Section titled “Verification Steps”1. Verify Hostname
Section titled “1. Verify Hostname”Check that the hostname matches expected servers:
| Hostname Pattern | Expected Source |
|---|---|
web-prod-* | Production web servers |
api-prod-* | Production API servers |
db-prod-* | Production database servers |
*-staging-* | Staging environment |
2. Verify IP Address
Section titled “2. Verify IP Address”Confirm IP is from a known network:
| IP Range | Environment |
|---|---|
192.168.1.0/24 | Production |
192.168.2.0/24 | Staging |
10.0.0.0/8 | Internal |
3. Verify Timing
Section titled “3. Verify Timing”Check when the registration occurred:
| Timing | Interpretation |
|---|---|
| Just now | Expected during deployment |
| Hours ago | May be legitimate, verify |
| Days ago | Likely stale, investigate |
4. Verify Thumbprint
Section titled “4. Verify Thumbprint”For pre-registered clients, verify thumbprint matches:
# On the target server, get the certificate thumbprint (built-in command)tarsus show-thumbprint
# Compare with registration thumbprint in MantisTenant Assignment
Section titled “Tenant Assignment”During Approval
Section titled “During Approval”Assign registrations to tenants for multi-tenant environments:
┌─────────────────────────────────────────────────────────────┐│ Tenant Assignment │├─────────────────────────────────────────────────────────────┤│ ││ Select Tenant: ││ ○ None (Global) ││ ● Acme Corp ││ ○ Beta Inc ││ ○ Gamma LLC ││ ││ ┌───────────────────────────────────────────────────────┐ ││ │ Assigning to tenant restricts this target to only │ ││ │ receive deployments from that tenant. │ ││ └───────────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────────┘Assigning a Tenant
Section titled “Assigning a Tenant”Tenant assignment for a target is performed in Lens or via the REST API, not
through mantisctl cert. After approving a registration, set the target’s tenant
from the target’s detail view in Lens, or pre-scope registrations by issuing a
tenant-scoped registration token (mantisctl registration create --tenant-id <id>).
Rejection
Section titled “Rejection”When to Reject
Section titled “When to Reject”Reject registrations when:
| Reason | Action |
|---|---|
| Unknown source | Reject, investigate |
| Wrong network | Reject, contact team |
| Suspicious timing | Reject, alert security |
| Duplicate | Reject duplicate |
| Expired request | Reject stale entries |
Rejecting via UI
Section titled “Rejecting via UI”┌─────────────────────────────────────────────────────────────┐│ Reject Registration │├─────────────────────────────────────────────────────────────┤│ ││ You are rejecting: ││ Client: unknown-01 ││ IP: 10.0.0.50 ││ ││ Reason (optional but recommended): ││ [Unknown source - not from expected network ] ││ ││ ┌───────────────────────────────────────────────────────┐ ││ │ The registration will be marked as rejected. The │ ││ │ client must re-register if this was a mistake. │ ││ └───────────────────────────────────────────────────────┘ ││ ││ [Cancel] [Reject] ││ │└─────────────────────────────────────────────────────────────┘Rejecting via CLI
Section titled “Rejecting via CLI”# Reject a registration (by ID or thumbprint prefix)mantisctl cert reject <id> --reason "Unknown source"Automation
Section titled “Automation”Auto-Approval
Section titled “Auto-Approval”To skip manual approval, register agents with a registration token that has
auto-approve enabled. Clients that register using such a token are approved
automatically — there is no separate conditional rules engine (no
approve-by-IP-range or approve-by-hostname-pattern rules). The only auto-approve
mechanism is the per-token auto_approve flag.
See Registration Tokens for how to create an auto-approving token and the trade-offs involved.
Webhook Notifications
Section titled “Webhook Notifications”Receive notifications for pending registrations by configuring a webhook
notification channel and subscribing it to the client_registration_pending
event. This is done through the REST API or the Lens notifications settings;
there is no mantisctl webhook subcommand.
First, create a webhook channel:
curl -X POST https://mantis.example.com/api/v1/notifications/channels \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "registration-notify", "channel_type": "webhook", "webhook_url": "https://hooks.example.com/registration" }'Then create a subscription that filters on the registration event, using the channel ID returned above:
curl -X POST https://mantis.example.com/api/v1/notifications/subscriptions \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "pending-registrations", "channel_id": "<channel-id>", "filters": [ { "filter_type": "event_type", "filter_values": ["client_registration_pending"] } ] }'Audit Trail
Section titled “Audit Trail”Approval Records
Section titled “Approval Records”Registration approval and rejection actions are logged to the server’s structured
log output (at INFO level). Approval events include the client name, thumbprint,
and the identity of the approver; rejection events include the same fields plus the
rejection reason.
Viewing Approval History
Section titled “Viewing Approval History”Until database audit logging is implemented for registrations, use mantisctl cert list to inspect current registration state:
# List all registrations and their current statusmantisctl cert list --status approved --verbose
# List rejected (revoked) registrationsmantisctl cert list --status revoked --verboseBest Practices
Section titled “Best Practices”1. Establish Verification Process
Section titled “1. Establish Verification Process”Define a standard verification process:
## Registration Approval Checklist
Before approving, verify:
1. [ ] Hostname matches naming convention2. [ ] IP address is from expected network3. [ ] Registration timing matches deployment4. [ ] If pre-registered, thumbprint matches5. [ ] Requestor has documented the need (ticket #)2. Use Tenant Assignment
Section titled “2. Use Tenant Assignment”Always assign to appropriate tenant:
| Environment | Tenant Assignment |
|---|---|
| Production | Production tenant |
| Staging | Staging tenant |
| Development | Development tenant |
| Shared | No tenant (global) |
3. Document Approval Decisions
Section titled “3. Document Approval Decisions”Include notes with every approval:
mantisctl cert approve <id> \ --notes "Ticket: OPS-1234, Requestor: Alice, Purpose: New web cluster"4. Regular Queue Review
Section titled “4. Regular Queue Review”Review pending queue regularly:
- Daily for high-security environments
- Weekly for standard environments
- Immediately for unexpected registrations
5. Clean Up Stale Entries
Section titled “5. Clean Up Stale Entries”Remove old pending registrations:
# List pending registrations to identify stale entriesmantisctl cert list --status pending --verbose
# Reject stale entries individually (by ID or thumbprint prefix)mantisctl cert reject <id> \ --reason "Auto-rejected: registration expired"Troubleshooting
Section titled “Troubleshooting”Cannot Find Registration
Section titled “Cannot Find Registration”Cause: Registration may have been rejected or expired
Solution:
- Check if registration was previously rejected
- Ask agent administrator to re-register
- Check audit logs for rejection event
Approval Failing
Section titled “Approval Failing”Cause: Permission or validation issue
Solution:
- Verify user has approval permission
- Check if registration is still pending
- Review error message for specific issue
Wrong Tenant Assigned
Section titled “Wrong Tenant Assigned”Cause: Incorrect selection during approval
Solution:
- Update the target’s tenant assignment from the target detail view in Lens
- Or revoke the registration and re-register with a tenant-scoped token
Next Steps
Section titled “Next Steps”- Registration Tokens - Automated registration
- Certificate Thumbprints - Pre-registration
- Overview - Return to registration overview