Registration Tokens

Register agents with pre-shared tokens.

What Are Registration Tokens?

Registration tokens allow agents to register automatically without manual approval:

Token Properties

Property	Description	Example
Name	Human-readable identifier	CI/CD Deployments
Token	Secret value (shown once)	abc123def456...
Max Uses	Usage limit (optional)	100
Expires At	Expiration date (optional)	2024-12-31
Auto-Approve	Skip manual approval	true / false
Default Environment	Pre-assign environment	Production
Default Roles	Pre-assign roles	web-server
Tenant	Restrict to tenant	Acme Corp

Token Status

Status	Description	Can Register?
Active	Token can be used	Yes
Revoked	Token has been revoked	No

Note

A token’s stored status is either active or revoked. Even when active, a token may be blocked from use if it has exceeded its max_uses limit or its expires_at timestamp has passed. Both conditions are enforced at registration time via the token’s can_be_used check, which requires the token to be active, not exhausted, and not expired.

Creating Tokens

Via Lens UI

┌─────────────────────────────────────────────────────────────┐
│  Create Registration Token                                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Name *                                                     │
│  [Production Web Servers                    ]               │
│                                                             │
│  ─────────────────────────────────────────────────────────  │
│                                                             │
│  Limits:                                                    │
│  Max Uses:     [100        ]  (leave empty for unlimited)   │
│  Expires:      [2024-12-31 ]  (leave empty for no expiry)   │
│                                                             │
│  ─────────────────────────────────────────────────────────  │
│                                                             │
│  Registration Behavior:                                     │
│  ☑ Auto-approve registrations using this token              │
│                                                             │
│  Default Environment:                                       │
│  [Production                    ▼]                          │
│                                                             │
│  Default Roles:                                             │
│  [web-server                    ] [+ Add]                   │
│                                                             │
│  Tenant (optional):                                         │
│  [Acme Corp                     ▼]                          │
│                                                             │
│                                     [Cancel]  [Create]      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Via CLI

# Create basic token
mantisctl registration create --name "Development Servers"

# Create token with limits
mantisctl registration create --name "Production Web Servers" \
  --max-uses 100 \
  --expires-hours 8760

# Create auto-approving token with defaults
mantisctl registration create --name "CI/CD Deployments" \
  --auto-approve true \
  --environment Production \
  --roles "web-server,app-server"

# Create tenant-scoped token
mantisctl registration create --name "Acme Deployments" \
  --tenant-id 42 \
  --auto-approve true

Via REST API

Tokens can also be created programmatically with POST /api/v1/registration-tokens (on Mandible’s REST port, 3000 by default). The request needs an authenticated bearer token whose principal holds the registration_tokens:create permission, and the plaintext token is returned once in the response.

curl -X POST https://mandible.example.com:3000/api/v1/registration-tokens \
  -H "Authorization: Bearer $MANTIS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Deployments",
    "max_uses": 100,
    "expires_at": "2025-12-31T23:59:59Z",
    "auto_approve": true,
    "default_environment": "Production",
    "default_roles": ["web-server", "app-server"],
    "tenant_id": "0190c3a1-2b4c-8def-9012-3456789abcde"
  }'

Field	Type	Required	Description
name	string	Yes	Human-readable token name (1–255 chars)
max_uses	integer	No	Maximum registrations allowed (omit for unlimited)
expires_at	string (ISO 8601)	No	Expiry timestamp (omit for never)
auto_approve	boolean	No	Auto-approve clients registered with this token (default false)
default_environment	string	No	Environment assigned to registered clients
default_roles	string[]	No	Roles assigned to registered clients
tenant_id	string (UUID)	No	Tenant (UUID) the token belongs to
expected_common_name	string	No	Required CSR common name for this token (case-insensitive)

The plaintext token value appears only in this response — store it securely.

Token Display

Caution

The token value is only shown once when created. Store it securely.

┌─────────────────────────────────────────────────────────────┐
│  Token Created Successfully                                 │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Name: Production Web Servers                               │
│                                                             │
│  Token (save this now - it won't be shown again):           │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6 │ │
│  │                                                 [Copy] │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│  Max Uses: Unlimited      Auto-Approve: Yes                 │
│  Expires: 2024-04-15      Environment: production           │
│                                                             │
│                                               [Done]        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Managing Tokens

Token List

┌─────────────────────────────────────────────────────────────┐
│  Registration Tokens                                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  [+ New Token]        Filter: [All         ▼]               │
│                                                             │
│  ┌─────────────────────┬──────────┬────────┬─────────────┐ │
│  │ Name                │ Status   │ Uses   │ Expires     │ │
│  ├─────────────────────┼──────────┼────────┼─────────────┤ │
│  │ Production Web      │ ● Active │ 24/100 │ Dec 31      │ │
│  │ CI/CD Deployments   │ ● Active │ 156/∞  │ Never       │ │
│  │ Staging Servers     │ ● Active │ 8/50   │ Mar 1       │ │
│  │ Old Token           │ ✗ Revoked│ 45/100 │ -           │ │
│  │ Past-Expiry Token   │ ● Active │ 20/50  │ Jan 1 (past)│ │
│  └─────────────────────┴──────────┴────────┴─────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Token Detail

┌─────────────────────────────────────────────────────────────┐
│  Token: Production Web Servers                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Status: ● Active                                           │
│                                                             │
│  ─────────────────────────────────────────────────────────  │
│                                                             │
│  Usage:                                                     │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ Uses: 24 of 100                                       │ │
│  │ ████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 24%          │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│  Configuration:                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ Auto-Approve: Yes                                     │ │
│  │ Default Environment: Production                       │ │
│  │ Default Roles: web-server                             │ │
│  │ Tenant: Acme Corp                                     │ │
│  │ Expires: December 31, 2024                            │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│  Created: January 15, 2024 by admin@example.com             │
│                                                             │
│  Recent Registrations:                                      │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ web-prod-24    192.168.1.124    Jan 20, 2024         │ │
│  │ web-prod-23    192.168.1.123    Jan 18, 2024         │ │
│  │ web-prod-22    192.168.1.122    Jan 15, 2024         │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│                               [Edit]  [Revoke]              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Via CLI

# List all tokens
mantisctl registration list

# Output:
# NAME                    STATUS    USES      EXPIRES
# Production Web Servers  active    24/100    2024-12-31
# CI/CD Deployments       active    156/∞     never
# Staging Servers         active    8/50      2024-03-01
# Old Token               revoked   45/100    -

# Show token details (by token ID)
mantisctl registration show <token-id>

# Revoke a token (by token ID)
mantisctl registration revoke <token-id> --reason "No longer needed"

# Delete a token (by token ID)
mantisctl registration delete <token-id>

Note

There is no registration update subcommand. To change a token’s limits, revoke it and create a replacement. Tokens are referenced by their UUID, not by name.

Using Tokens

Configuring Tarsus Agent

Provide the token when registering the agent:

# Register with token (--mandible-endpoint is the Mandible gRPC host:port)
tarsus register \
  --mandible-endpoint mandible.example.com:50052 \
  --token "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

# Output:
# Registering with Mantis server...
# Registration successful!
# Status: approved (auto-approved via token)
# Ready to receive deployments.

Configuration File

Tarsus uses a TOML config file. Set the registration token and the Mandible server address there:

/etc/mantis/tarsus.toml

name = "web-prod-01"

[mandible]
endpoint = "mandible.example.com:50052"

[registration]
enabled = true
token = "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

Environment Variable

# Set via environment, then start in registration mode
export TARSUS__REGISTRATION__TOKEN="a1b2c3d4e5f6g7h8..."
tarsus register --mandible-endpoint mandible.example.com:50052

Auto-Approval

With Auto-Approve Enabled

Without Auto-Approve

Choosing Auto-Approve

Scenario	Auto-Approve	Reason
Trusted network	Yes	All agents are legitimate
CI/CD pipeline	Yes	Automated provisioning
Public network	No	Manual verification needed
High security	No	Always verify identity
Development	Yes	Speed over security
Production	Depends	Based on risk tolerance

Caution

Auto-approve should only be used when you can trust all systems that have access to the token.

Token Security

Secure Storage

DO	DON’T
Store in secrets manager	Commit to version control
Use environment variables	Log token values
Rotate regularly	Share tokens broadly
Use per-environment tokens	Use one token for everything

Token Rotation

Create new token and phase out old one:

# 1. Create new token
mantisctl registration create --name "Production Web Servers v2" \
  --auto-approve true \
  --environment Production

# 2. Update agents to use new token
# (during next deployment or maintenance)

# 3. Inspect old token usage
mantisctl registration show <old-token-id>

# 4. Revoke old token when no longer in use
mantisctl registration revoke <old-token-id> \
  --reason "Rotated to v2"

Limiting Token Exposure

Limit	Purpose
Max uses	Limit total registrations
Expiration	Force regular rotation
Tenant restriction	Scope to specific tenant
Environment default	Pre-assign to environment

Common Patterns

Per-Environment Tokens

# Development token - unlimited, auto-approve
mantisctl registration create --name "Development" \
  --auto-approve true \
  --environment Development

# Staging token - limited, auto-approve
mantisctl registration create --name "Staging" \
  --max-uses 50 \
  --auto-approve true \
  --environment Staging

# Production token - limited, manual approval
mantisctl registration create --name "Production" \
  --max-uses 100 \
  --auto-approve false \
  --environment Production

Per-Tenant Tokens

# Token for Acme Corp (tenant ID 42)
mantisctl registration create --name "Acme Corp Servers" \
  --tenant-id 42 \
  --auto-approve true

# Token for Beta Inc (tenant ID 43)
mantisctl registration create --name "Beta Inc Servers" \
  --tenant-id 43 \
  --auto-approve true

Time-Limited Tokens

# Token for a specific deployment window (~90 days)
mantisctl registration create --name "Q1 Rollout" \
  --max-uses 50 \
  --expires-hours 2160 \
  --auto-approve true

Revoking Tokens

When to Revoke

Situation	Action
Token exposed	Revoke immediately
Project ended	Revoke token
Rotation	Revoke after migration
Security incident	Revoke all tokens

Revocation Process

┌─────────────────────────────────────────────────────────────┐
│  Revoke Token                                               │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  You are revoking:                                          │
│  Token: Production Web Servers                              │
│  Current Uses: 24 of 100                                    │
│                                                             │
│  Reason:                                                    │
│  [Token exposed in logs - rotating to new token    ]        │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ ⚠ Revoking this token will prevent new registrations │ │
│  │   using it. Existing registrations are not affected. │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│                                     [Cancel]  [Revoke]      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# Revoke via CLI (by token ID)
mantisctl registration revoke <token-id> \
  --reason "Token exposed - rotating"

Best Practices

1. Use Descriptive Names

# Good
mantisctl registration create --name "Production Web Servers Q1 2024"
mantisctl registration create --name "CI/CD Pipeline - Jenkins"

# Avoid
mantisctl registration create --name "token1"
mantisctl registration create --name "temp"

2. Set Appropriate Limits

Environment	Max Uses	Expiration
Development	Unlimited	90 days
Staging	50	30 days
Production	100	365 days

3. Use Per-Purpose Tokens

Don’t use one token for everything:

# Separate tokens for different purposes
mantisctl registration create --name "Web Servers"
mantisctl registration create --name "API Servers"
mantisctl registration create --name "Background Workers"

4. Monitor Token Usage

# Regular usage check
mantisctl registration list

# Inspect a specific token's usage
mantisctl registration show <token-id>

5. Document Token Purpose

Keep records of:

• Why token was created
• Who has access
• When it should be rotated
• What systems use it

Troubleshooting

Token Not Accepted

Cause: Token may be revoked, expired, or exhausted

Solution:

# Check token status (by token ID)
mantisctl registration show <token-id>

# Verify token value is correct
# Check for copy/paste errors

Registration Still Pending

Cause: Token doesn’t have auto-approve enabled

Solution:

1. Check token configuration
2. Either manually approve
3. Or create new token with auto-approve

Token Usage Not Incrementing

Cause: Agent using old/different token

Solution:

1. Verify agent configuration
2. Check agent logs for token being used
3. Restart agent after configuration change

Next Steps

• Certificate Thumbprints - Pre-registration workflow
• Approving Registrations - Manual approval
• Overview - Return to registration overview