> 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/operations/rebuild-the-authorization-graph.md).

# Rebuild the authorization graph

Establish that a stale authorization graph is why a correct membership row and a wrong effective answer coexist, and get the rebuild done through the one route that exists.

## What this is, and when you need it

Effective access is computed from a graph rather than evaluated per request, so a correct membership row and a wrong effective answer can coexist. Rebuilding the graph is the repair for exactly one symptom: an entitlement was granted or revoked, the membership row is visibly correct in the Webconsole, and the user's *effective* access still disagrees. If the membership row itself is wrong, a rebuild will faithfully rebuild the wrong answer, so no other symptom belongs here.

{% hint style="warning" %}
**No screen rebuilds the graph — but it is not a support ticket either.** Nothing in the Webconsole rebuilds the authorization graph and no shipped batch task can be scheduled to, so the diagnosis on this page is entirely yours. The rebuild itself is one request against `openiam-esb`, which step 3 gives. It needs network access to that service rather than a console login, so on a deployment you do not operate yourself it stays a request to whoever does — but it is a request for one command, not for an operation only OpenIAM can perform.
{% endhint %}

## At a glance

|                          |                                                                                                                                                                                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **You will end up with** | The evidence that the graph and the membership rows disagree, the rebuild requested, and the user's effective access agreeing with their membership afterwards. No membership, role or resource data changes                                 |
| **Where**                | **Debug Authorization**, `/webconsole/authorizationDebug` — there is no menu entry, so type the route — plus the user's own entitlement screens. The rebuild itself is not on any screen                                                     |
| **You need first**       | Confirmation that the membership row is correct, the user and resource in dispute named, and the effective-access answer recorded before anything changes                                                                                    |
| **Takes**                | 15–30 minutes to establish the diagnosis; the rebuild runs in the background once it is triggered                                                                                                                                            |
| **Reversible**           | Yes — the graph is derived data, so the correction for a bad rebuild is another rebuild once the membership is right; what no screen tells you is that a rebuild failed hard, dropped the graph indices and stopped the auth-manager service |

## Before you begin

Record the effective-access answer for your test user **before** anything is rebuilt, because the before-and-after comparison is the only verification there is. This operation changes state, so follow [Change configuration safely](/administration-guide/start/change-safely.md) and record when it ran.

## Establish the diagnosis and get the rebuild done

{% stepper %}
{% step %}

### Confirm the membership row first

Open the user, role or group in the Webconsole and read the membership back. If membership is wrong, stop: the rebuild will faithfully rebuild the wrong answer, and the fix is the membership.
{% endstep %}

{% step %}

### Record what the graph believes now

**Debug Authorization** at `/webconsole/authorizationDebug` is the screen for asking what the graph currently holds for one user: fill **User ID** and **Resource Name** and press **Check Authorization**, and the answer comes back under **Is User Entitled?**. Note it for the entitlement in dispute.

{% hint style="warning" %}
**On this build the screen's own form does not work.** **Check Authorization** submits the value under a different name from the one the page accepts, so the request is rejected before any answer is computed and the result panel never appears. Confirm the behaviour on your own release. Where it reproduces, the observable substitute is the symptom itself: read the user's effective access on the screen that shows it — their entitlement list, or the resource they cannot reach — and record *that* before and after. Report the form defect to OpenIAM support.
{% endhint %}
{% endstep %}

{% step %}

### Trigger the rebuild

`openiam-esb` exposes the rebuild as a plain `GET`, so one request runs it:

{% code overflow="wrap" %}

```bash
curl http://localhost:9080/openiam-esb/authmanager/rebuildGraph
```

{% endcode %}

Record when you ran it, because nothing on any screen shows you that afterwards. If you do not operate the deployment, this is where it becomes a request to whoever does — name the symptom, membership correct and effective access wrong, with the user and resource you recorded.

{% hint style="info" %}
**A response means the request was accepted, not that the graph was rebuilt.** The endpoint puts a message on the queue for `auth-manager` and returns without waiting for it, with no body. Everything you learn about how the rebuild actually went comes from the log lines under [Verification](#verification).
{% endhint %}

{% hint style="warning" %}
A rebuild that fails hard drops the graph indices and stops the auth-manager service, and no OpenIAM screen reports that. The `auth-manager` log is the only place it shows: `Can't rebuild graph` marks a failed rebuild.
{% endhint %}
{% endstep %}

{% step %}

### Ask again, and compare

Re-read the same effective-access answer for the same user and compare it with what you recorded. A rebuild that finished and a rebuild that was merely accepted are indistinguishable from anything except that comparison — so make it, and do not accept "the rebuild has been triggered" as evidence.
{% endstep %}
{% endstepper %}

## Verification

The before-and-after comparison of the same user's effective access is the verification. The `auth-manager` log carries the confirmation underneath it: `Creation (or fail) of authorization objects in graph database took <n> ms` marks the end of a rebuild, and `Can't rebuild graph` marks a failed one. Neither line reaches a screen — [Which log answers which question](/administration-guide/operations/which-log-to-read.md) is how to ask for that log.

## When it goes wrong

| Symptom                                                                      | Cause                                                                                                              | Where to look / fix                                                                                                                      |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Membership correct, effective access wrong                                   | Stale authorization graph                                                                                          | Record the effective answer, then trigger the rebuild as above                                                                           |
| The rebuild ran and the answer did not change                                | The membership itself is wrong, so the rebuild reproduced it                                                       | Fix the membership, then rebuild once more                                                                                               |
| Effective access is still wrong and a rebuild appeared to run                | The rebuild failed rather than finished                                                                            | `auth-manager` log: `Can't rebuild graph`. A hard failure drops the graph indices and stops the service, which no OpenIAM screen reports |
| **Check Authorization** returns an error instead of an answer                | The screen's form submits a value the page does not accept                                                         | Use the user's own entitlement screens as the before-and-after reading instead, and report the defect                                    |
| Asked the deployment owner to change `gremlin.endpoint` and nothing happened | Two shipped keys are misspelled `gremilin.endpoint` and `gremilin.port`; the corrected spelling is read by nothing | Quote the misspelling — [Search indexes and the authorization graph](/administration-guide/reference/search-indexes.md)                  |
| Object correct on its own screen, invisible in search                        | A stale index, not the graph                                                                                       | [Rebuild a search index](/administration-guide/operations/rebuild-a-search-index.md)                                                     |

## Rollback or cleanup

There is nothing to undo. The graph is derived data, rebuilt from membership rows that are still there, so the correction for a bad rebuild is another rebuild once the underlying membership is right.

## The other graph repairs, which really do have no trigger

OpenIAM can repair graph data inconsistencies and remove expired edges as well. Neither is on a screen, and — unlike the rebuild — neither is exposed as a request: `openiam-esb` publishes the rebuild and nothing else, so these two reach the graph only as messages on the queue. Both are genuinely support-driven, and if a support engineer asks you to run one, that is the mechanism they mean.

## Related

* [Search indexes and the authorization graph](/administration-guide/reference/search-indexes.md) — the graph connection settings, including the two misspelled keys
* [Rebuild a search index](/administration-guide/operations/rebuild-a-search-index.md) — the other derived structure that goes stale, and the one you can rebuild yourself
* [Diagnose a failed operation](/administration-guide/operations/diagnose-a-failed-operation.md) — where the graph sits among the ten evidence layers
* [Change configuration safely](/administration-guide/start/change-safely.md) — the standard this operation assumes

*Applies to OpenIAM 2026.8.1. Last reviewed 12 October 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/operations/rebuild-the-authorization-graph.md?ask=<question>&goal=<user_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.