> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/identities/related-accounts.md). # Manage related accounts Link a privileged or non-production user record to the person who owns it. ## What this is, and when you need it A **related account** links two OpenIAM *users* — a person and a second, higher-privilege account belonging to them. Use it when that second account needs its own entitlements and lifecycle but must stay traceable to its human owner. ## At a glance | | | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **You will end up with** | Two user records linked by a typed relationship | | **Where** | `/webconsole/user-related-accounts?id=` | | **You need first** | Both user records, a `RELATED_ACCOUNT_ASSOCIATION_TYPE` metadata type, and a PBAC policy granting you `MANAGE_RELATED_ACCOUNTS` on the user. See [Grant access to user administration](/administration-guide/identities/grant-user-administration.md) | | **Takes** | A minute | | **Reversible** | Yes — remove the link; neither record is affected | ## Link the two accounts {% stepper %} {% step %} ### Confirm you have a relationship type to use The relationship-type drop-down on the related accounts screen lists the metadata types in the `RELATED_ACCOUNT_ASSOCIATION_TYPE` grouping. Three ship: | `TYPE_ID` | English display name | Ships since | | -------------------- | ---------------------- | ----------- | | `AD_DEV_ACCOUNT` | Ad development account | 4.2.0.5 | | `AD_STAGE_ACCOUNT` | Ad staging account | 4.2.0.5 | | `PRIVILEGED_ACCOUNT` | Privileged Account | 4.2.1.10 | The first two are named for a specific Active Directory pattern rather than as generic categories, so most deployments add their own at **Administration → Metadata Types**. The drop-down populates from the grouping, not from a hard-coded list. `PRIVILEGED_ACCOUNT` is the one to reach for when you are tracking administrative second accounts. {% endstep %} {% step %} ### Open the person's related accounts screen `/webconsole/user-related-accounts?id=`. The screen has two views, selected by a `type` value in the address bar: it defaults to `related`, and the other value is `primary`. A user has at most **one** primary account and any number of related accounts. {% endstep %} {% step %} ### Add the second account, with its relationship type Pick the other user record and the relationship type, and save. The audit event is `ADD_ACCOUNT`. {% hint style="warning" %} **The `type` value in the address bar is matched case-insensitively, and anything that is not `primary` is treated as related** — including a typo. Hand-edit the address to `primry` and you silently add a related account rather than a primary one, with no error. The audit event's `Relation type` target attribute holds the value that was actually used, which is where you confirm which kind of link you got. Navigate between the two views from the screen rather than by editing the address. {% endhint %} {% endstep %} {% endstepper %} ## Why this and not a second identity A related account is not an identity on a managed system, and it is not an orphan. When a second administrative account keeps colliding with a person's identity on a managed system — the "User already has an identity for this managed system" failure — this is the model that resolves it: the second account becomes its own user record with its own entitlements, linked back to its human owner. See [Resolve orphan accounts](/administration-guide/identities/resolve-orphan-accounts.md). ## Verification An `ADD_ACCOUNT` audit event carrying two target attributes: `Relation type`, holding `primary` or `related`, and `Relation meta type`, holding the association type's name. The success message is "Account added". The link is also visible from user search: the `hasRelatedAccounts` and `relationship` columns can be added to the user search grid, so related accounts become a thing you can report on rather than a thing you have to open each record to see. See [User search configuration](/administration-guide/reference/user-search-configuration.md). ## When it goes wrong | Symptom | Cause | Fix | | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | --------------------------------------------------------------- | | "Related account could not be added: a user cannot be linked to themselves as a related account" | The account ID equals the user ID | Pick a different account | | "This relationship already exists" when adding a **primary** account | A primary account is already set, and only one is permitted | Remove the existing primary account first, then add the new one | | "This relationship already exists" when adding a related account | That exact link already exists | Nothing to do | | "An error occurred while assigning the related account" | The save itself failed | Read the audit event; the failure reason is on it | | The relationship type you want is not offered | No metadata type for it in the `RELATED_ACCOUNT_ASSOCIATION_TYPE` grouping | Add one at **Administration → Metadata Types** | ## Roll it back Reversible. Remove the link from the same screen; the audit action is `REMOVE_ACCOUNT`. Removing the link does not change either user record and does not touch any entitlement or identity on either of them. ## Related * [Resolve orphan accounts](/administration-guide/identities/resolve-orphan-accounts.md) — where an orphan should become a second account rather than a second identity * [Grant and revoke access](/administration-guide/identities/grant-and-revoke-access.md) — entitling the second account once it exists * [User search configuration](/administration-guide/reference/user-search-configuration.md) — the `hasRelatedAccounts` and `relationship` search columns *Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/administration-guide/identities/related-accounts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.