Skip to main content
Version: 2.52.20

Create Application Registration

EasyLife 365 Collaboration applications are accessible via the Microsoft identity platform and offer various scopes that client applications can use. These scopes enable authorized users and client apps to access EasyLife 365 Collaboration API endpoints based on permissions.

To use an API, we'll first register a client app, grant it access to EasyLife 365 Collaboration application, and authorize the necessary scopes. By specifying EasyLife 365 Collaboration 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).
  5. Select the desired application to view the available scopes.
  6. Select Delegated permissions and choose the required scopes. Note that some scopes 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. Which application you pick in step 3 depends on the route:

  • EasyLife 365 Admin offers the manage roles (Collab.Manage.ReadWrite.All and Collab.Manage.Read.All) for the versioned routes under /admin.
  • EasyLife 365 Collaboration offers the create roles (Collab.Site.Provisioning.ReadWrite.All, Collab.Guest.Provisioning.ReadWrite.All and Collab.Provisioning.ReadWrite.All) for creating sites and inviting guests.
  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 or EasyLife 365 Collaboration.
  4. Select Application permissions instead of Delegated permissions.
  5. Choose the permission named by the route you intend to call, for example Collab.Manage.ReadWrite.All. Each route's reference page lists the permissions it accepts, and Call the API as an application lists them all.
  6. Select Grant admin consent.
warning

An application permission that has been added but not admin-consented has no effect, and the API rejects the resulting token. Step 6 is mandatory, not optional.

Only the versioned routes (with /v1/ in the path) accept an application permission. Every other route answers 403 to an application token. Groups cannot be created by an application yet.

An application permission is not narrowed by any user's rights. Grant the narrowest role that is enough: Collab.Manage.Read.All for an integration that only reads, Collab.Manage.ReadWrite.All to also change groups, guests, OneDrive accounts, SharePoint sites and fields, and the site or guest create role for provisioning. The role Collab.Config.ReadWrite.All no longer exists. Use Collab.Manage.ReadWrite.All instead.

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. A certificate is the better choice. Keep a client secret in a secret store and never in a script or in source control.

  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 API you call: admin for the manage routes and collab for the routes that create sites and guests. 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.easylife365.cloud/admin/.default

For the create routes, use https://api.easylife365.cloud/collab/.default as the scope.

Send the resulting token as a bearer token on the API request:

Authorization: Bearer {access-token}
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.