Agent Authentication

Agent Tokens

The agent authenticates with the jokowipe.id API using agent tokens — signed JWTs generated in the dashboard.

Generating a Token

1. Go to Dashboard → Settings → Agents
2. Click New Agent Token
3. Give the token a name (e.g., "prod-db-server-01")
4. Set an optional expiration date
5. Click Generate
6. Copy the token immediately — it is shown only once

One-Time Display

Agent tokens are shown only once at generation time. If you lose the token, you must revoke it and generate a new one.

Token Properties

Property	Value
Format	JWT (HS256)
Lifetime	Configurable (default: no expiry)
Refresh	Auto-refreshed by the agent before expiry
Scope	Tied to a specific organization
Permissions	Execute backup jobs only (cannot modify org settings)

Configuring the Token

In the Config File (Recommended)

agent:
  token: "${JOKOWIPE_AGENT_TOKEN}"

Set the environment variable:

export JOKOWIPE_AGENT_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

For systemd services, add to the environment file:

# /etc/jokowipe/agent.env
JOKOWIPE_AGENT_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Reference the env file in the systemd unit:

[Service]
EnvironmentFile=/etc/jokowipe/agent.env

Interactive Authentication

jokowipe-agent auth --token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
# ✓ Token validated
# ✓ Agent registered as: prod-db-server-01
# ✓ Organization: Acme Corp (org-a1b2c3)
# Token saved to /etc/jokowipe/agent.yaml

Token Rotation

To rotate an agent token:

1. Generate a new token in the dashboard (the old one stays valid)
2. Update the token in the agent config or environment variable
3. Restart the agent: sudo systemctl restart jokowipe-agent
4. Verify the agent connects successfully
5. Revoke the old token in the dashboard

This approach ensures zero downtime during rotation.

Revoking a Token

To revoke an agent token:

1. Go to Settings → Agents
2. Find the token by name
3. Click Revoke

The token is invalidated immediately. The agent will fail to authenticate on its next heartbeat and log an error.

Multiple Agents

Each agent should use a separate token. This allows you to:

• Revoke access for individual servers without affecting others
• Track which agent performed each backup
• Set per-agent expiration policies

Network Requirements

The agent only needs outbound access:

Destination	Port	Protocol	Purpose
api.jokowipe.id	443	HTTPS	Control plane communication
Your storage bucket	443	HTTPS	Backup file upload

No inbound ports need to be opened.

Mutual TLS (mTLS)

For enterprise deployments, you can configure mutual TLS between the agent and API:

tls:
  ca_cert: "/etc/jokowipe/ca.pem"
  client_cert: "/etc/jokowipe/client.pem"
  client_key: "/etc/jokowipe/client-key.pem"

Contact jokowipe.id@gmail.com for enterprise certificate issuance.