HridaOne Service Account

A dedicated HridaOne Admin account the HR Agent uses when no per-user Keycloak token is available.

The service account lets the HR Agent call HridaOne APIs on behalf of your organization — for system-triggered workflows, cron jobs, and as the fallback when users log in with email/password rather than SSO. It should be a purpose-created account, not a personal login.

---

Why a service account?

The HR Agent resolves HridaOne credentials in this priority order:

1. Per-user Keycloak token from Redis — only available when the user logged in via SSO
2. HRIDAONE_JWT_TOKEN — a pre-issued token pasted into config.json
3. Email/password login — the service account; auto-logins and auto-refreshes on expiry

Priorities 2 and 3 both use the service account credentials. The account must have the ADMIN role in HridaOne so it can read org-wide data when acting on behalf of employees.

---

Creating the service account

Option A — Setup script

Create the account first

HridaOne only lets an authenticated admin call /api/auth/register, so the script can't create the account on its own. Create it in the admin panel (Option B) first, then run the script — it verifies the login and writes config.json.

Run the helper script from the hr-agent directory:

cd hrida-ai-studio/scripts/hr-agent

python create_service_account.py \
  --api-url  http://localhost:8081 \
  --email    hr-agent@yourcompany.com \
  --password "HrAgent@2024!" \
  --tenant   ""

What the script does:

Step	Action
1	Checks HridaOne is reachable at --api-url
2	Tries to login with the given credentials
3	If login fails, tries POST /api/auth/register (fails unless registration is open) and prints the manual steps
4	Logs in again to confirm the account works end-to-end
5	Updates hrida-mcpo/config.json with the new credentials

Options:

Flag	Default	Description
--api-url	$HRIDAONE_API_URL or http://localhost:8081	HridaOne backend URL
--tenant	$HRIDAONE_TENANT_CODE or empty	Tenant code — leave empty for single-tenant
--email	hr-agent@hrida.ai	Service account email
--password	HrAgent@2024!	Service account password
--config	auto-detected	Path to hrida-mcpo/config.json
--dry-run	off	Print what would happen without making any changes

Dry run example:

python create_service_account.py --dry-run

Option B — HridaOne admin panel (recommended)

1. Log in to HridaOne as a Global Admin.
2. Go to Admin → Users → + Add Employee.
3. Fill in:
   • Full Name: HR Agent (Service Account)
   • Email: hr-agent@yourcompany.com
   • Role: ADMIN
   • Department: Human Resources
4. Save, then set a password via the Reset Password option.
5. Run create_service_account.py with the same email/password — it will detect the existing account and only update config.json.

Option C — Direct API call

Call the register endpoint with an admin's token:

curl http://localhost:8081/api/auth/register \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName":    "HR Agent (Service Account)",
    "email":       "hr-agent@yourcompany.com",
    "password":    "HrAgent@2024!",
    "role":        "ADMIN",
    "department":  "Human Resources",
    "position":    "HR Agent Bot",
    "joiningDate": "2024-01-01"
  }'

Add "tenantCode": "YOUR_CODE" if using multi-tenant mode.

---

Verifying the account

# 1. Login and get a token
TOKEN=$(curl -s http://localhost:8081/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"hr-agent@yourcompany.com","password":"HrAgent@2024!"}' \
  | python -c "import sys,json; print(json.load(sys.stdin)['data']['token'])")

# 2. Confirm the profile
curl http://localhost:8081/api/auth/me \
  -H "Authorization: Bearer $TOKEN"

The response should show "role": "ADMIN" and the email you registered.

---

Updating config.json

The setup script writes these fields into hrida-mcpo/config.json automatically. To update manually:

"hr-agent": {
  "env": {
    "HRIDAONE_API_URL":            "http://localhost:8081",
    "HRIDAONE_EMAIL":              "hr-agent@yourcompany.com",
    "HRIDAONE_PASSWORD":           "HrAgent@2024!",
    "HRIDAONE_JWT_TOKEN":          "",
    "HRIDAONE_TENANT_CODE":        "",
    "HRIDAONE_USE_PER_USER_TOKEN": "true",
    "REDIS_URL":                   "redis://localhost:6379"
  }
}

After any config change, restart mcpo to pick up the new values:

cd hrida-mcpo
uvx hrida-mcpo --config config.json --port 8009

---

Using a pre-issued JWT (HRIDAONE_JWT_TOKEN)

If you want to skip the login call at startup, paste the service account's JWT token directly into config.json:

"HRIDAONE_JWT_TOKEN": "eyJhbGciOiJIUzI1NiJ9..."

Important: HridaOne native JWTs expire in 24 hours. When the token expires, the agent automatically re-logs in with HRIDAONE_EMAIL/HRIDAONE_PASSWORD and continues without any restart. The HRIDAONE_JWT_TOKEN value is only used on first call; subsequent refreshes use the email/password path.

Leave HRIDAONE_JWT_TOKEN empty to always start with an email/password login — simpler and equally reliable.

---

Security recommendations

Recommendation	Why
Use a dedicated account, not a personal login	Avoids tying agent availability to an employee's account status
Use a strong, unique password	The password is stored in config.json — treat the file as a secret
Store config.json outside version control	Add hrida-mcpo/config.json to .gitignore
Use Docker secrets or env injection in production	Don't commit passwords to the repo in any environment
Grant ADMIN role — no more	The service account only needs read access to org data; ADMIN is the minimum HridaOne role that grants this

---

Related

• HR Agent — Full setup and feature reference
• SSO Integration — Per-user Keycloak tokens (eliminates the service account fallback for SSO users)
• Digital Employees Overview — Multi-agent platform introduction