> 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/developer-guide/developerguide.md).

# Developer Guide

Extend OpenIAM — write Groovy scripts for provisioning, synchronisation, reconciliation and batch work, and integrate with the REST API.

This guide is for extending OpenIAM: writing the Groovy scripts that carry your organisation's rules, and integrating other systems with the REST API.

It assumes you can write code, that you have a running OpenIAM deployment to work against, and that you have not read anything else about the product.

**Start with** [***Choose what you are building***](/developer-guide/choose-what-youre-building.md)**.** It matches what you are trying to do to the pages that do it, in order.

## What this guide covers

| Area                 | Use it for                                                                                                                                                                                                     |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Groovy scripting** | The platform's extension points — what value an attribute carries when an account is provisioned, how an inbound row maps onto a user, what happens when reconciliation finds a difference, and scheduled work |
| **The REST API**     | Integrating another system with OpenIAM: creating and searching users, triggering provisioning, reading audit data                                                                                             |

**Groovy is where most customisation happens.** The API is how other systems talk to OpenIAM; scripts are how OpenIAM's own behaviour is shaped. Most projects need both, and most start with scripts.

## What this release of the guide covers

**Groovy scripting is covered in full for the five extension points most projects use**: policy map, transformation, validation and attributes, reconciliation, and batch. Provisioning pre- and post-processors, workflow scripts and access-management scripts are extension points this release does not yet document; the shipped scripts under `conf/iamscripts/` are the reference for those in the meantime.

**The REST API section covers the fundamentals** — registering an OAuth client, authenticating, which response envelope each kind of endpoint returns, error handling and finding an operation — then the token lifecycle, the provisioning API that carries every change to a user, and a walkthrough that exercises them end to end.

Not covered here at all: building a connector and the connector SDK, the data model, branding, and per-language API walkthroughs. Administration — configuring managed systems, policies, workflows and campaigns — is the [Administration Guide](/administration-guide/admin.md). Deploying the platform is the [Installation Guide](/installation/installation.md). Design decisions taken before configuration are in the [Solution Architecture and Design Guide](/solution-architecture/solution-architecture.md).

## How this guide is written

**Every class, method, path and version in these pages was read from the product source**, not from earlier documentation. Where a page shows a shipped script, it is quoted from the scripts that ship under `conf/iamscripts/` rather than written for the occasion.

Examples that would print a credential, or that would work only on one deployment, are not used. Where a value is yours to supply, the page says so and names it.

## How commands and examples are written

Code you can copy appears in a fenced block. Values you supply appear as a named variable, set once at the top of a page:

| Variable          | What to set it to                             |
| ----------------- | --------------------------------------------- |
| `OPENIAM_URL`     | The address your deployment is published on   |
| `OPENIAM_VERSION` | The release you are developing against        |
| `SERVICE_ACCOUNT` | The account your integration authenticates as |

Angle brackets — `<like this>` — appear only where a value is illustrative rather than something you set once.

## If you get stuck

Every page ends with a symptom table: what you see, what it means, what to do. [*Common errors*](/developer-guide/common-errors.md) collects the ones that span more than one page.

## Related

* [*Choose what you are building*](/developer-guide/choose-what-youre-building.md) — start here
* [*How scripting works*](/developer-guide/how-scripting-works.md) — read before any scripting tutorial
* [*API fundamentals*](/developer-guide/fundamentals.md) — read before writing an integration
* [*Managing users*](/developer-guide/user-lifecycle.md) — the provisioning API
* The [Installation Guide](/installation/installation.md), [Administration Guide](/administration-guide/admin.md) and [Solution Architecture and Design Guide](/solution-architecture/solution-architecture.md)

*Applies to OpenIAM 2026.8.1.*


---

# 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/developer-guide/developerguide.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.