Skip to main content
Version: 1.7.0

API Token Agent & User Agent Runtime

Overview​

Legacy backend support for the auto-attributes platform: optional agent linkage on API tokens and runtime tracking of IP Magic Box clients on user documents. Enables neo-backend Bcyip-Agent validation for agent tokens (e.g. Tower iptower) while keeping manual IP Magic Box deposits on legacy routes unchanged.

How it works​

Two MongoDB surfaces are involved:

  1. apitokens.agent (optional string) — Set manually via Retool or Compass. Read by neo-backend auth as apiTokenAgent for POST /api/v2/documents validation. Not set automatically for magic-box / Azure tokens.

  2. users.agents (map) + legacy users.agent — Updated by the legacy backend when an IP Magic Box token is created or reused (name = magic-box or Azure).

IP Magic Box token refresh​

apiTokenService.buildIpmagicboxUserUpdate() writes:

  • boxVersion, currentJob (legacy)
  • agent: { name: 'ipmagicbox', version, platform, lastSeen }
  • agents.ipmagicbox: { version, platform, lastSeen }

Called on token create and on reuse when an existing non-expiring magic-box / Azure token is found.

Key files​

  • app/database/schema/api-token.js — Optional agent field on token schema
  • app/database/schema/user.js — agents mixed map; computedAgent virtual for JSON responses
  • app/services/api-token.js — buildIpmagicboxUserUpdate(), hook on createApiToken
  • app/routes/api-token.js — Token creation entry points (password, company, disposable)

Technical decisions​

  • No HTTP admin for apitokens.agent: Ops set agent names in Mongo/Retool to avoid widening the legacy admin surface. Tower tokens get agent: 'iptower' before neo agent ingest goes live.
  • Dual write (users.agent + users.agents): Dashboard and legacy code still read users.agent; neo and platform APIs prefer users.agents keyed by agent name.
  • IP Magic Box tokens stay agent-less on apitokens: Manual deposit does not call neo POST /documents; no Bcyip-Agent / token agent check on legacy routes.
  • Neo-backend auto-attributes: neo/features/auto-attributes.md (when published in internal docs)
  • Forge createdDate selection: required for neo/agent deposits to enter the protect pipeline

Known issues​

  • Existing production magic-box tokens do not have apitokens.agent — expected; not required for manual deposit.
  • platform is 'unknown' on legacy token create until clients send platform in the token request body.

Next steps​

  • Retool workflow to tag Tower tokens with agent: 'iptower'
  • Optional: set apitokens.agent: 'ipmagicbox' if neo ever validates magic-box on v2 routes