Worlds / Hr and identity

Microsoft Entra API

A local Microsoft Entra ID tenant with users, groups, directory roles, app registrations and conditional access policies. Test the agent that disables accounts, manages role assignments and changes access policy.

Base path: /v1.0
Auth: OAuth bearer token (Microsoft Graph), the world key
Endpoints: 18
Status: Active today

This reference previews the surface the Microsoft Entra world serves in the closed beta. Paths mirror the public Microsoft Entra API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_MICROSOFT_ENTRA_URL`	This world's origin followed by `/v1.0`
`WORLDS_API_KEY`	The world key, accepted wherever Microsoft Entra expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · @microsoft/microsoft-graph-client

import { Client } from "@microsoft/microsoft-graph-client";

const client = Client.init({
  baseUrl: process.env.WORLDS_MICROSOFT_ENTRA_URL + "/v1.0",
  authProvider: (done) => done(null, process.env.WORLDS_API_KEY),
});

const users = await client.api("/users").top(20).get();

API reference

18 of 18

Users

Directory users with profile and account state.

GET/v1.0/usersList users
POST/v1.0/usersCreate a user
GET/v1.0/users/{id}Get a user
PATCH/v1.0/users/{id}Update a user
DELETE/v1.0/users/{id}Delete a user
GET/v1.0/users/{id}/memberOfList a user's groups and roles

Fields · 6

`id`	string	Object id
`displayName`	string	Display name
`userPrincipalName`	string	Sign in name
`accountEnabled`	boolean	Whether the account can sign in
`jobTitle`	string	Job title
`department`	string	Department

Groups

Security and Microsoft 365 groups.

GET/v1.0/groupsList groups
POST/v1.0/groupsCreate a group
GET/v1.0/groups/{id}/membersList group members
POST/v1.0/groups/{id}/members/$refAdd a member to a group
DELETE/v1.0/groups/{id}/members/{memberId}/$refRemove a member from a group

Fields · 5

`id`	string	Group id
`displayName`	string	Group name
`securityEnabled`	boolean	Usable for access control
`groupTypes`	array	Unified or dynamic markers
`membershipRule`	string	Rule for dynamic groups

Applications and service principals

App registrations and their enterprise app instances.

GET/v1.0/applicationsList applications
POST/v1.0/applicationsCreate an application
GET/v1.0/servicePrincipalsList service principals
POST/v1.0/servicePrincipals/{id}/appRoleAssignedToAssign an app role

Fields · 4

`id`	string	Object id
`appId`	string	Client id
`displayName`	string	App name
`signInAudience`	string	Who can sign in to the app

Audit trail of who signed in and how it went.

GET/v1.0/auditLogs/signInsList sign ins
GET/v1.0/auditLogs/directoryAuditsList directory audit events
GET/v1.0/auditLogs/signIns/{id}Get a sign in

Fields · 5

`id`	string	Log entry id
`createdDateTime`	datetime	Time of the sign in
`userPrincipalName`	string	User who signed in
`appDisplayName`	string	App signed in to
`status`	object	Error code and failure reason

Test workflow

Prepare. Select the Microsoft Entra setup for your workflow and review its starting records, including users, groups, applications and service principals.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

alex.w accountEnabled is false
alex.w sign-in sessions revoked
sam.t User Administrator assignment removed
Require MFA for admins still report-only
Break-glass account keeps Global Administrator

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Microsoft Entra
version: 2
connector: microsoft-entra
seed: microsoft-entra-starter
mode: isolated
policy: >
  Respond to ticket 3381. Disable alex.w and revoke all sign-in sessions, and
  remove the expired User Administrator assignment for sam.t. Do not change
  any conditional access policy.
tasks:
  - id: disable-a-compromised-account-and-revoke-its-sign-in-sessions
    prompt: Disable a compromised account and revoke its sign-in sessions
  - id: remove-an-expired-directory-role-assignment
    prompt: Remove an expired directory role assignment
  - id: rotate-a-client-secret-on-an-app-registration
    prompt: Rotate a client secret on an app registration
expected:
  - alex.w accountEnabled is false
  - alex.w sign-in sessions revoked
  - sam.t User Administrator assignment removed
  - Require MFA for admins still report-only
  - Break-glass account keeps Global Administrator
scenarios:
  - throttled
  - insufficient-privileges
  - token-expired

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`throttled`	Graph returns 429 with Retry-After on /users
`insufficient-privileges`	403 Authorization_RequestDenied on a role change
`token-expired`	401 InvalidAuthenticationToken mid run
`not-found`	404 Request_ResourceNotFound for a deleted object
`replication-lag`	A new group member is missing on the next read

Starting data

Start each run from the same records and relationships. The overview below describes the Microsoft Entra starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
users	220 members and 30 guests with accountEnabled and department
groups	Security and Microsoft 365 groups, some with dynamic membership
directory roles	Global Administrator, User Administrator and Helpdesk Administrator assignments
conditional access	6 policies, enabled, disabled or report-only
app registrations	12 apps with client secrets and expiry dates

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Users records

Users

Directory users with profile and account state.

Field	Type	Meaning / relationship
`id`	string	Object id
`displayName`	string	Display name
`userPrincipalName`	string	Sign in name
`accountEnabled`	boolean	Whether the account can sign in
`jobTitle`	string	Job title
`department`	string	Department

json · illustrative record shape

{
  "id": "<Object id>",
  "displayName": "<Display name>",
  "userPrincipalName": "<Sign in name>",
  "accountEnabled": false,
  "jobTitle": "<Job title>",
  "department": "<Department>"
}

See users operations

Groups records

Groups

Security and Microsoft 365 groups.

Field	Type	Meaning / relationship
`id`	string	Group id
`displayName`	string	Group name
`securityEnabled`	boolean	Usable for access control
`groupTypes`	array	Unified or dynamic markers
`membershipRule`	string	Rule for dynamic groups

json · illustrative record shape

{
  "id": "<Group id>",
  "displayName": "<Group name>",
  "securityEnabled": false,
  "groupTypes": [],
  "membershipRule": "<Rule for dynamic groups>"
}

See groups operations

Applications and service principals records

Applications and service principals

App registrations and their enterprise app instances.

Field	Type	Meaning / relationship
`id`	string	Object id
`appId`	string	Client id
`displayName`	string	App name
`signInAudience`	string	Who can sign in to the app

json · illustrative record shape

{
  "id": "<Object id>",
  "appId": "<Client id>",
  "displayName": "<App name>",
  "signInAudience": "<Who can sign in to the app>"
}

See applications and service principals operations

Audit trail of who signed in and how it went.

Field	Type	Meaning / relationship
`id`	string	Log entry id
`createdDateTime`	datetime	Time of the sign in
`userPrincipalName`	string	User who signed in
`appDisplayName`	string	App signed in to
`status`	object	Error code and failure reason

json · illustrative record shape

{
  "id": "<Log entry id>",
  "createdDateTime": "<Time of the sign in>",
  "userPrincipalName": "<User who signed in>",
  "appDisplayName": "<App signed in to>",
  "status": {}
}

See sign in logs operations

See the Microsoft Entra world in the catalog

Microsoft Entra API

Connect

API reference

Users

Groups

Applications and service principals

Sign in logs

Test workflow

What to verify

Test file

Failure conditions

Starting data

Users

Groups

Applications and service principals

Sign in logs