Skip to main content
Version: Insiders

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​

  1. Log in to the Entra ID Portal and navigate to the App registrations blade. Select New registration.
  2. 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​

  1. Navigate to the Authentication settings.
  2. Enable the Allow public client flows setting. 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.

  1. Go to the API Permissions settings.
  2. Select the Add a permission option, which will launch the Request API permissions wizard.
  3. Switch to the APIs my organization uses section.
  4. Use the search box to filter for EasyLife to display the EasyLife applications registered in your tenant (EasyLife 365 or EasyLife 365 Admin Insiders).
  5. Select EasyLife 365 Admin Insiders to view the available scopes.
  6. Select Delegated permissions and choose Config.ReadWrite.All. Note that this scope may require Admin 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.

  1. Go to the API Permissions settings.
  2. Select the Add a permission option, then switch to the APIs my organization uses section.
  3. Search for EasyLife and select EasyLife 365 Admin Insiders.
  4. Select Application permissions instead of Delegated permissions.
  5. 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.
  6. Select Grant admin consent.
warning

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 toGrant
Read ownersIdentity.Ownership.Read.All
Synchronize owners, and change what technical and business owners may doIdentity.Ownership.ReadWrite.All
Read the name, policy and compliance of applicationsIdentity.Manage.Read.All
Assign or clear the policy of applications, and do everything the roles above allowIdentity.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.

  1. Go to the Certificates & secrets settings.
  2. Add a New client secret, or upload a certificate under Certificates.
  3. 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: ******
note

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.

note

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).

  1. 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.
  2. Request a token with the .default scope (see Request an app-only token).
  3. 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.

MethodRouteWhat it doesDelegated scopeApplication rolesRate limit
GET/v1/manage/apps/{id}Reads the name, policy and compliance of an applicationConfig.ReadWrite.AllIdentity.Manage.Read.All, Identity.Manage.ReadWrite.AllRead
PATCH/v1/manage/apps/{id}Assigns or clears the policy of an applicationConfig.ReadWrite.AllIdentity.Manage.ReadWrite.AllBulk operations
GET/v1/apps/{id}/ownershipReads the owners of an applicationConfig.ReadWrite.AllIdentity.Ownership.Read.All, Identity.Ownership.ReadWrite.All, Identity.Manage.ReadWrite.AllRead
PUT/v1/apps/{id}/ownershipReplaces the owners of an applicationConfig.ReadWrite.AllIdentity.Ownership.ReadWrite.All, Identity.Manage.ReadWrite.AllBulk operations
GET/v1/apps/{id}/ownership/permissionsReads what owners may doConfig.ReadWrite.AllIdentity.Ownership.Read.All, Identity.Ownership.ReadWrite.All, Identity.Manage.ReadWrite.AllRead
PATCH/v1/apps/{id}/ownership/permissionsChanges what owners may doConfig.ReadWrite.AllIdentity.Ownership.ReadWrite.All, Identity.Manage.ReadWrite.AllBulk 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:

PropertyDescription
codeThe name of the error, for example Identity.PolicyNotFound. It does not change: read this one.
titleA 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.
detailWhat went wrong and what to fix.
statusThe HTTP status.
requestIdThe 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"
}
StatuscodeMeaning
400InvalidPayloadThe request could not be read, or a value is wrong. Nothing was changed.
401AuthenticationRequiredNo token, an expired token or a token for another API.
403NotAllowedThe token has no role for this route, a read role was used to write, or the route does not accept application tokens.
403Identity.LicenseRequiredThe tenant has no Professional or Trial license.
404NotFoundThe application does not exist in your tenant, with this type.
429noneToo 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.