Create Application Registration
EasyLife 365 Identity Insiders administration endpoints are exposed on the shared EasyLife 365 Admin Insiders application and are accessible via the Microsoft identity platform. They offer both delegated and application scopes that client applications can use. These scopes enable authorized users and unattended callers to access EasyLife 365 Identity Insiders API endpoints based on permissions.
To use an API, we'll first register a client app, grant it access to EasyLife 365 Admin Insiders application, and authorize the necessary scopes. By specifying EasyLife 365 Admin Insiders application API scopes during the registration of your client app, you enable the client app to acquire an access token containing those scopes from the Microsoft identity platform.
Register a Client App
New Registration
- Log in to the Entra ID Portal and navigate to the App registrations blade. Select
New registration. - Provide a display Name for your application, which will be visible to users of your application, and create the application.
Once the registration is complete, the Microsoft Entra admin center will display the app registration's Overview pane. Make a note of the Application (client) ID and the Directory (tenant) ID as these will be necessary for authenticating your PowerShell scripts.
Authentication
- Navigate to the
Authenticationsettings. - Enable the
Allow public client flowssetting. This is only needed for delegated flows that sign a user in interactively — an app-only integration does not require it.
Delegated permissions
Delegated permissions let the client app call the API on behalf of a signed-in user. The effective rights are the intersection of the permission and what that user is allowed to do.
- Go to the
API Permissionssettings. - Select the
Add a permissionoption, which will launch theRequest API permissionswizard. - Switch to the
APIs my organization usessection. - Use the search box to filter for EasyLife to display the EasyLife applications registered in your tenant (EasyLife 365 or EasyLife 365 Admin Insiders).
- Select EasyLife 365 Admin Insiders to view the available scopes.
- Select
Delegated permissionsand chooseConfig.ReadWrite.All. Note that this scope may requireAdmin consent.
Application permissions
Application permissions let a daemon, script or scheduled automation call the API without a signed-in user, authenticating as itself. They are offered by the EasyLife 365 Admin Insiders application for the administrative endpoints under /admin.
- Go to the
API Permissionssettings. - Select the
Add a permissionoption, then switch to theAPIs my organization usessection. - Search for EasyLife and select EasyLife 365 Admin Insiders.
- Select
Application permissionsinstead ofDelegated permissions. - Choose the permission named by the endpoint you intend to call — for example
Identity.Ownership.ReadWrite.All. Each endpoint's reference page lists the permissions it accepts. - Select
Grant admin consent.
EasyLife 365 Admin Insiders requires an explicit application role assignment. An application permission that has been added but not admin-consented has no effect, and the API rejects the resulting token — so step 6 is mandatory, not optional.
An application permission is not narrowed by any user’s rights, so grant the narrowest one that does the job:
| The integration needs to | Grant |
|---|---|
| Read owners | Identity.Ownership.Read.All |
| Synchronize owners, and change what technical and business owners may do | Identity.Ownership.ReadWrite.All |
| Read the name, policy and compliance of applications | Identity.Manage.Read.All |
| Assign or clear the policy of applications, and do everything the roles above allow | Identity.Manage.ReadWrite.All |
Every role applies to all applications in the tenant. With either Identity.Manage.ReadWrite.All or Identity.Ownership.ReadWrite.All, the calling application can let the technical owners of any application, including applications EasyLife 365 Identity Insiders does not own, change technical owners, business owners and app settings. Treat an application that holds either of them as a privileged identity: limit who owns it and who can manage its credentials, and limit who holds the Entra roles that can add a credential to it.
Roles do not include one another: each route lists every role that opens it. Identity.Manage.ReadWrite.All is listed on the ownership calls because it manages applications as a whole, and the Identity.Ownership.* roles are not listed on the policy calls. A read role cannot write: the call answers 403 Forbidden.
Add a credential
Application permissions use the client credentials flow, so the app authenticates with its own credential rather than a user's sign-in.
- Go to the
Certificates & secretssettings. - Add a
New client secret, or upload a certificate underCertificates. - Record the secret value immediately — it is not shown again.
Request an app-only token
Request the token from your own tenant, using the .default scope of the EasyLife 365 Admin Insiders API. The returned token carries the granted permissions in its roles claim.
POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={client-id}
&client_secret={client-secret}
&grant_type=client_credentials
&scope=https://api.insiders.easylife365.cloud/admin/.default
Send the resulting token as a bearer token on the API request:
Authorization: ******
A newly created client secret can take a few seconds to become usable. Until then the token request fails with AADSTS7000215: Invalid client secret provided — retry rather than recreating the secret.
Application-owner writes additionally require the EasyLife 365 Identity Insiders service principal to already own the target Entra application or enterprise application. See Get Application Ownership and Replace Application Ownership for the ownership prerequisite.
Call the API as an application
An application token has no signed-in person behind it. It carries the granted roles in its roles claim and no scp claim. Only the versioned routes (/v1/) accept it: every other route answers 403 Forbidden to an application token. The roles are defined on the EasyLife 365 Admin Insiders API, the same API the Identity routes are served from, so every token in this section is requested for https://api.easylife365.cloud/admin/.default (Insiders: api.insiders.easylife365.cloud).
- Register the client application, add a credential and grant the role (the sections above). In the Microsoft Entra admin center this is API permissions → Add a permission → APIs my organization uses → EasyLife 365 Admin Insiders → Application permissions → pick the role → Grant admin consent.
- Request a token with the
.defaultscope (see Request an app-only token). - Call the route with
Authorization: Bearer <token>.
This example requests a token and reads the policy state of an application:
TOKEN=$(curl -s -X POST "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \
-d "client_id=$CLIENT_ID" -d "client_secret=$CLIENT_SECRET" \
-d "grant_type=client_credentials" \
-d "scope=https://api.easylife365.cloud/admin/.default" | jq -r .access_token)
curl -s "https://api.easylife365.cloud/admin/identity/v1/manage/apps/57523d68-2913-4fc0-8f91-af100f37562f?type=appRegistration" \
-H "Authorization: Bearer $TOKEN"
$ErrorActionPreference = "Stop"
$tenantId = "[TENANT_ID]"
$clientId = "[CLIENT_ID]"
$clientSecret = "[CLIENT_SECRET]" # read it from your secret store, never hard-code it
$token = Invoke-RestMethod -Method POST `
-Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" `
-ContentType "application/x-www-form-urlencoded" `
-Body @{
client_id = $clientId
client_secret = $clientSecret
grant_type = "client_credentials"
scope = "https://api.easylife365.cloud/admin/.default"
}
Invoke-RestMethod -Method GET -Headers @{ "Authorization" = "Bearer $($token.access_token)" } `
-Uri "https://api.easylife365.cloud/admin/identity/v1/manage/apps/57523d68-2913-4fc0-8f91-af100f37562f?type=appRegistration"
Routes, scopes and roles
Every call needs a Professional license. A role from the list opens the route, and it does not matter which one of them the token carries. The delegated scope applies to a signed-in administrator.
| Method | Route | What it does | Delegated scope | Application roles | Rate limit |
|---|---|---|---|---|---|
| GET | /v1/manage/apps/{id} | Reads the name, policy and compliance of an application | Config.ReadWrite.All | Identity.Manage.Read.All, Identity.Manage.ReadWrite.All | Read |
| PATCH | /v1/manage/apps/{id} | Assigns or clears the policy of an application | Config.ReadWrite.All | Identity.Manage.ReadWrite.All | Bulk operations |
| GET | /v1/apps/{id}/ownership | Reads the owners of an application | Config.ReadWrite.All | Identity.Ownership.Read.All, Identity.Ownership.ReadWrite.All, Identity.Manage.ReadWrite.All | Read |
| PUT | /v1/apps/{id}/ownership | Replaces the owners of an application | Config.ReadWrite.All | Identity.Ownership.ReadWrite.All, Identity.Manage.ReadWrite.All | Bulk operations |
| GET | /v1/apps/{id}/ownership/permissions | Reads what owners may do | Config.ReadWrite.All | Identity.Ownership.Read.All, Identity.Ownership.ReadWrite.All, Identity.Manage.ReadWrite.All | Read |
| PATCH | /v1/apps/{id}/ownership/permissions | Changes what owners may do | Config.ReadWrite.All | Identity.Ownership.ReadWrite.All, Identity.Manage.ReadWrite.All | Bulk operations |
The routes start with https://api.easylife365.cloud/admin/identity. A token for another API, or without a matching role, never opens a route. When audit logging is turned on for the tenant, the audit history records an application as the actor of a change it makes.
Errors
Errors are application/problem+json:
| Property | Description |
|---|---|
code | The name of the error, for example Identity.PolicyNotFound. It does not change: read this one. |
title | A short text. For some errors it still holds an older value such as EL0001, which is kept for existing integrations. Do not build on it. |
detail | What went wrong and what to fix. |
status | The HTTP status. |
requestId | The id of the request. Give it to support when a call keeps failing. |
{
"type": "https://docs.easylife365.cloud/errors/not-allowed",
"title": "EL0002",
"status": 403,
"code": "NotAllowed",
"requestId": "e5d4c3b2-a190-4876-9f5e-0d1c2b3a4f60"
}
| Status | code | Meaning |
|---|---|---|
400 | InvalidPayload | The request could not be read, or a value is wrong. Nothing was changed. |
401 | AuthenticationRequired | No token, an expired token or a token for another API. |
403 | NotAllowed | The token has no role for this route, a read role was used to write, or the route does not accept application tokens. |
403 | Identity.LicenseRequired | The tenant has no Professional or Trial license. |
404 | NotFound | The application does not exist in your tenant, with this type. |
429 | none | Too many requests. The answer is a short text with a Retry-After header, not a JSON body. Wait and retry. |
Each reference page lists the errors of its route.