lytics-account

Account

Account management for Lytics: users and roles, API tokens, and settings on the current account, plus copying metadata and configuration between two accounts (sync, compare, resume). Reads are safe; every write changes who can reach the account or what it does, so nothing is written unless the user explicitly asks.

Before you start

• Credentials: references/auth.md. Single-account modes use LYTICS_API_TOKEN / LYTICS_API_URL; sync uses two accounts and the Multi-Account section (profile config, src / dst helpers).
• Request conventions and error shapes: references/api.md. Users and tokens mostly use /v2 (errors in .errors[0].message); settings and token creation use /api (errors in .message).
• Every write goes through references/confirmation-gate.md. Removals and revocations also need an explicit "this cannot be undone" in the summary.
• FilterQL parsing (sync, for INCLUDE slug): references/filterql-grammar.md.

Gotchas

Users, roles, tokens, settings:

• Role updates are a full replace. POST /v2/user/{id}/roles sets the user's whole role list on this account; send current roles plus the change (users.md).
• Role slugs are not validated on users: a typo is stored and grants nothing. Check slugs against GET /v2/account/{aid}?roles=true -> roles_available (can_be_assigned: true).
• POST /v2/user on an existing member resets their roles here and on every child account (to only authed2 if roles is omitted). Use it only to invite.
• Removing a user is irreversible: DELETE /v2/user/{id} drops their access, and deletes the user entirely if this was their last account. The API has no last-admin check; never leave the account without an admin, and don't remove or demote the caller unless asked.
• Token creation needs a user (login) token. POST /api/auth/createtoken with an API token returns 403 Not authorized: This endpoint is available only via user tokens.
• A token's value is shown once, in the create response; reads never return it. A token created without expires never expires.
• Revoking a token is a permanent delete (DELETE /v2/auth/{id}); every client using it breaks. The same endpoint deletes integration credentials, so confirm type == "lytics-auth-token"; never revoke internal tokens or the session's own token.
• api_ip_whitelist can lock everyone out, this session included: requests from IPs outside it get 403, and a locked-out caller cannot undo it. Security-category settings change every user's login. Both need a retype gate (settings.md).

Sync between accounts:

• Every call goes through the src / dst helpers from references/auth.md, never LYTICS_API_URL / LYTICS_API_TOKEN -- an env-prefixed call silently hits the ambient account, so a "sandbox to prod" run can overwrite the sandbox source. This applies to every snippet borrowed from a peer skill.
• Same-account guard: resolve each profile's own aid (references/auth.md); halt if either aid fails to resolve or the two match. Print both aids in the plan header.
• Jobs are created with POST /v2/job?run_job=false. run_job defaults to true, so a synced export would start sending immediately. Never auto-start a job (writes.md).
• Job updates are full-object PUTs. PUT /v2/job/{workflow}/{id} clears omitted description, quiet-window fields, expires_at, meta, hidden, verbose_logging, and a sent config replaces the stored one wholesale.
• Writable is not the same as safe to copy. can_be_assigned: true only means the API accepts a write. security/API categories, cull_user_filter, workflow_exclude_segments, enable_schema_patches, schema_user_private_fields are excluded from sync settings (sync-settings.md).
• idconfig needs an extra retype gate: after the plan yes, the user must type exactly confirm idconfig <table>; it can re-merge every profile in the destination (sync-settings.md).
• Never write a setting with can_be_assigned: false (403). Classify it drift-readonly; refuse an explicit sync setting <slug> for it.
• Never leave an orphan draft schema patch. On halt, delete it (or prompt to apply); only a failed apply leaves the draft for inspection (safety.md).
• Schema-write mode comes from dst /api/account/setting/enable_schema_patches, not from listing patches (that returns 200 everywhere); re-probe after a settings phase.
• Stop on first error; never auto-copy OAuth auths; flow running state is never copied as running.
• Never alter the trace-line or schema publish-tag formats (normalization.md, writes.md): already-synced destination objects carry them and compare strips that exact pattern.

Modes

Read the mode file before acting in that mode.

Mode	When	File
users	Who is on the account, what roles exist, invite a user, change roles, remove a user	users.md
tokens	List or inspect API tokens, create one, rotate, revoke	tokens.md
settings	Read or change a setting on the current account	settings.md
sync	Copy objects or settings from one account to another (sync <type> ... from <src> to <dst>)	sync.md, then workflow.md
compare	Read-only audit of two accounts (compare [<type>] from <src> to <dst>)	sync.md, workflow.md
resume	Continue a halted sync from its manifest (resume <manifest-path>)	workflow.md, safety.md

Sync topic files (read the one for the step you are on): dependencies.md, normalization.md, writes.md, sync-settings.md, safety.md. sync.md has the full verb grammar, types, selectors, flags, and step list.

Related skills

• the lytics-audiences skill -- segment create/update conventions; single-account segment work.
• the lytics-schema skill -- schema patches, direct publish, idconfig/rank endpoints, enable_schema_patches migration.
• the lytics-flows skill -- flow payloads.
• the lytics-integrations skill -- jobs, connections, integration auths, webhook templates; starting a synced job (created with run_job=false).