Your first calls
Authenticate, search for a user, create one, change its state and remove it — a complete first integration against a running deployment.
Applies to: OpenIAM 2026.8.1
One walkthrough, end to end: authenticate, find a user, create one, change its state, and remove it. Everything after this is the same pattern against different endpoints.
Do this against a test deployment. It creates and deletes a real user.
What this builds, and how long it takes
You get
A working integration you can build on, and a token-handling pattern that survives contact with production
Time
45 minutes
You need
A deployment, an OAuth client, and curl and jq
Reversible
Yes — the last step removes what the walkthrough created
Before you start
API fundamentals. Two behaviors in it will catch you out here if you have not read it: the HTTP status is not the outcome, and different kinds of endpoint answer with different envelopes.
An OAuth client registered in the console, with the
Client Credentialsgrant. API fundamentals step 1, Register a client and get a token creates one. Do that first — without it there is nothing to authenticate as.The rights the lifecycle operations need, on the account the client acts as — see step 6.
A test deployment. Not production.
Set these first
export OPENIAM_URL=<the address your deployment is published on>
export OPENIAM_CLIENT_ID=<the client id from your OAuth provider>Keep the secret out of your shell. Read it from your credential store at the point of use — the examples below assume $OPENIAM_CLIENT_SECRET is set by something other than you typing it.
Build it
1. Get a token
Expected: authenticated.
// empty is doing real work there. Without it, a failed request puts the literal string null into $TOKEN, every later call fails with an unrelated-looking error, and nothing points back at the token. Treat an absent token as a hard stop.
Every call from here carries it:
2. Search for a user
Start with a read. It confirms the token works before you change anything.
Expected: a count, emptySearchBean absent or false, and error null.
Searches take a structured body and page with from and size, not query parameters. They also require at least one criterion. A body carrying only paging comes back with emptySearchBean set and no results — the endpoint declines to return the whole population rather than doing it slowly. That is a safeguard, not a failure.
Results are in beans. Searches answer with the paged-read envelope, which has no status field — see API fundamentals.
3. Create a user
Expected: status: 200, an id in contextValues.userId, checkStatusInProgress: true, and errorList null or empty.
The new user's id comes back in contextValues.userId, not in primaryKey. This endpoint does not set primaryKey, even though the envelope has the field — see API fundamentals.
status is an integer here, and it is the outcome. The HTTP response is 200 whether the save succeeded or was refused — see API fundamentals.
checkStatusInProgress is always true on a successful save. Do not branch on it. It looks like a signal and is not one — the controller sets it unconditionally, and the version that computed it is commented out in the source. It exists so the console knows to start polling.
What does carry the per-system outcome is successMessage, which lists each managed system the user was provisioned to and the state of that account. An account still being written reads as PENDING_CREATE — and correspondingly PENDING_UPDATE, PENDING_DELETE, PENDING_DISABLE or PENDING_ENABLE for the other operations.
So confirm the outcome rather than assuming it, which is what step 4 does. An integration that creates a user and immediately asserts the account exists in Active Directory will fail intermittently, on timing.
Four things about that payload are worth knowing before you build on it:
metadataTypeIddecides what kind of user this is, and the type governs which attributes apply. Your deployment defines the available types; list them in the console before your first call.notifyUserViaEmailsends mail. Set itfalsein a walkthrough. Set it deliberately in an integration — this is the flag that emails a few thousand people when a bulk load goes wrong.Email and phone are typed and multi-valued.
typeIdselects which one; a user can carry several of each.publishedcontrols visibility to other users in the interface.
Omitting id is what makes this a create. The same endpoint updates when id is present, so a repeated call without it produces a second user rather than an error. Managing users.
If it fails, read errorList before anything else. An entry carrying validationError names the field and the reason, and that is almost always the whole answer.
4. Find what you created
contextValues.userId from step 3 is the identifier. To confirm it by search — and, because provisioning is asynchronous, to see what state the account is actually in:
Identifiers are opaque. Do not parse them or assume a format.
A freshly created user typically comes back with userStatus: "PENDING_INITIAL_LOGIN" — the account exists and has not been signed into yet.
5. Grant the user a role
Entitlements are granted through one endpoint, which takes the identifiers and the operation to apply:
Expected: status: 200.
The same call carries groupIds, resourceIds and organizationIds, and you can include several in one request. operation is ADD, REPLACE or DELETE.
There is no separate "provision" call. Granting the role triggers provisioning by itself, the same way creating the user did — OpenIAM pushes the entitlement out to the managed systems the role is tied to. Creating and entitling are the only two things you do; the target-system work follows from them.
A refusal arrives as status: 401 with ACCESS_DENIED, and a bad userId as status: 404 with USER_NOT_FOUND.
6. Change the user's state
The lifecycle operations are POST, and the identifier goes in the body. Not PUT, and not a query parameter.
Expected: status: 200.
enableUser takes the same shape. So do the other eight lifecycle transitions — Managing users lists them.
These operations check the requester's rights, and a valid token is not sufficient on its own. Disabling a user requires USER_EDIT_INFO and DISABLE_USER; enabling requires USER_EDIT_INFO and ENABLE_USER. Failing that, the operation is permitted when the target is one of the requester's subordinates. A refusal arrives as status: 401 with ACCESS_DENIED in errorList.
The call is synchronous. status: 200 means the platform performed the operation, not merely that it accepted the request — so you can read the result directly rather than polling.
7. Clean up
Confirm it is gone:
Verify it
Run the whole sequence once more from a clean shell. A walkthrough that only works the second time, or only with a token you already had, is not yet an integration.
The token request from a fresh shell
An access_token, first time
The search before any write
A count in beans, and error null
The create
status: 200 and an id in contextValues.userId
The role grant
status: 200, and the role visible on the user in the console
Disable, then enable
status: 200 from both
The removal, then the search
A count of zero
If it goes wrong
TOKEN REQUEST FAILED
The client id or secret is wrong, or the provider's grant is not Client Credentials
Check the pair, then the provider's configuration
$TOKEN contains null
The // empty guard is missing from the jq filter
Add it. A literal null string fails every later call obscurely
HTTP 403 on a call that should work
The client's scopes do not cover that path
Widen the scope on the provider to what is needed
HTTP 405 on disable or remove
The request used PUT or GET
These are POST
The search returns nothing although data exists
The body carried only paging, so emptySearchBean is set
Add at least one criterion
jq returns null for .data
Searches answer in beans
Read .beans
errorCode and fieldMappings are always null
Those belong to the internal service envelope
Read errorList
status: 401 with ACCESS_DENIED
The requester lacks a required right
Grant USER_EDIT_INFO and the operation's own right
status: 400 on the create
A field failed validation
Read errorList; an entry's validationError names the field
The create fails on metadataTypeId
That type does not exist on this deployment
List the available types in the console
A second user appears instead of an update
saveUser was sent without id
Include id to update
Everything returns HTTP 200 and nothing happens
The code is checking the HTTP status, not status in the body
What this procedure does not cover
The approval workflows that may sit in front of an entitlement request, and access rights with start and end dates. Bulk operations. Confirming that an account actually landed in a target system, which is the audit log's subject rather than this API's. OAuth and OpenID Connect flows beyond obtaining a token, which are the identity provider's own subject.
Related
API fundamentals — read first
Managing users — every provisioning operation, and the rights each needs
Last updated
Was this helpful?