{"title":"Using service-to-service (S2S) authentication","url":"https://jonas-paprotka.de/docs/dev-itpro/administration/automation-apis-using-s2s-authentication/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/automation-apis-using-s2s-authentication, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/automation-apis-using-s2s-authentication","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Service-to-service authentication enables external services to connect as an application, without impersonating normal users.","date":"2025-06-20","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Using service-to-service (S2S) authentication","slug":"using-service-to-service-s2s-authentication","at":0,"chars":11520},{"level":2,"title":"Feature availability","slug":"feature-availability","at":1203,"chars":504},{"level":2,"title":"Main usage scenarios","slug":"main-usage-scenarios","at":1707,"chars":1156},{"level":2,"title":"Business Central on-premises prerequisite","slug":"business-central-on-premises-prerequisite","at":2863,"chars":614},{"level":2,"title":"Set up service-to-service authentication","slug":"set-up-service-to-service-authentication","at":3477,"chars":338},{"level":2,"title":"Task 1: Register a Microsoft Entra application for authentication to Business Central","slug":"task-1-register-a-microsoft-entra-application-for-authentication-to-business-central","at":3815,"chars":3632},{"level":2,"title":"Task 2: Set up the Microsoft Entra application in Business Central","slug":"task-2-set-up-the-microsoft-entra-application-in-business-central","at":7447,"chars":1913},{"level":2,"title":"Calling API and web services OAuth2Flows","slug":"calling-api-and-web-services-oauth2flows","at":9360,"chars":2160},{"level":3,"title":"Define entity, like customers, items, or vendors","slug":"define-entity-like-customers-items-or-vendors","at":11443,"chars":77},{"level":1,"title":"@name auth","slug":"name-auth","at":11520,"chars":329},{"level":3,"title":"Variable Response","slug":"variable-response","at":11765,"chars":84},{"level":1,"title":"@name GetCompanies","slug":"name-getcompanies","at":11849,"chars":264},{"level":3,"title":"Variable Response","slug":"variable-response-1","at":11934,"chars":161},{"level":3,"title":"Get entities","slug":"get-entities","at":12095,"chars":18},{"level":1,"title":"@name GetEntities","slug":"name-getentities","at":12113,"chars":115},{"level":3,"title":"Create entity","slug":"create-entity","at":12209,"chars":19},{"level":1,"title":"@name CreateEntity","slug":"name-createentity","at":12228,"chars":194},{"level":3,"title":"Get created entity","slug":"get-created-entity","at":12398,"chars":24},{"level":1,"title":"@name GetCreatedEntity","slug":"name-getcreatedentity","at":12422,"chars":246},{"level":4,"title":"Variable Response","slug":"variable-response-2","at":12565,"chars":84},{"level":3,"title":"Modify entity","slug":"modify-entity","at":12649,"chars":19},{"level":1,"title":"@name ModifyEntity","slug":"name-modifyentity","at":12668,"chars":219},{"level":3,"title":"Delete entity","slug":"delete-entity","at":12868,"chars":19},{"level":1,"title":"@name DeleteItem","slug":"name-deleteitem","at":12887,"chars":1017}],"text":"# Using service-to-service (S2S) authentication\nService-to-Service (S2S) authentication is suited for scenarios where integrations are required to run without any user interaction. S2S authentication uses the Client Credentials OAuth 2.0 Flow<https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow>. This flow enables you to access resources by using the identity of an application.\n> NOTE\n> For more information about OAuth 2.0 flows, see OAuth 2.0 and OpenID Connect protocols on the Microsoft identity platform<https://learn.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols> in the Microsoft Entra ID documentation.\nIn contrast, OAuth delegate flows, like https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow, https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-implicit-grant-flow and resource owner password credentials<https://learn.microsoft.com/azure/active-directory/develop/v2-oauth-ropc> can be configured to require multifactor authentication (MFA). This configuration prevents unattended integrations because MFA is required to acquire the access token from Microsoft Entra ID.\n## Feature availability\nThe following table describes in which versions S2S authentication was made available for online or on-premises environments.\nAPI|Online|On-premises\nBusiness Central automation APIs|version 17.0|versions 18.11 and 19.5\nBusiness Central APIs v1.0|version 18.3|versions 18.11 and 19.5\nBusiness Central APIs v2.0|version 18.3|versions 18.11 and 19.5\nBusiness Central custom APIs|version 18.3|versions 18.11 and 19.5\nBusiness Central web services|version 18.3|versions 18.11 and 19.5\n## Main usage scenarios\nTwo main scenarios are enabled with S2S authentication:\n1. Company setup using automation API\n Automation APIs provide capability for automating company setup through APIs. The automation APIs are used to hydrate tenants, that is, to bring them to an initial state.\n The D365 Automation entitlements give access to APIs in the `/api/microsoft/automation` route by using the OAuth client credentials flow. An application token with the Automation.ReadWrite.All scope is needed for accessing Business Central Automation APIs.\n2. External user and non-interactive user access to APIs and web services.\n S2S authentication enables both external user and non-interactive user access to Business Central online. Refer to license guide<https://www.microsoft.com/licensing/product-licensing/dynamics365> for scenarios and usage. An application token with the API.ReadWrite.All scope is needed for accessing Business Central APIs and web services.\n> NOTE\n> When you use S2S authentication, you can now use the integration session to create scheduled tasks. This capability is supported on 21.2 and later versions of Business Central online.\n## Business Central on-premises prerequisite\nBusiness Central on-premises must be configured for Microsoft Entra authentication with OpenID Connect.\n> IMPORTANT\n> The ValidAudiences parameter of the Business Central must include the endpoint `https://api.businesscentral.dynamics.com`. If it doesn't, you get the error Authentication_InvalidCredentials on API requests, or the error securitytokeninvalidaudienceexception in the application log when you try to download symbols from Visual Studio.\nSee Configure Microsoft Entra authentication with OpenID Connect<authenticating-users-with-azure-ad-openid-connect>.\n## Set up service-to-service authentication\nTo set up service-to-service authentication, you have to do two things:\n Register an application in your Microsoft Entra tenant for authenticating API calls against Business Central.\n Grant access for that application in Business Central.\nThese tasks are described in the sections that follow.\n## Task 1: Register a Microsoft Entra application for authentication to Business Central\nComplete these steps to register an application in your Microsoft Entra tenant for service-to-service authentication.\n1. Sign in to the Microsoft Entra admin center<https://entra.microsoft.com>.\n2. Register an application for Business Central in Microsoft Entra tenant.\n Follow the general guidelines at Register your application with your Microsoft Entra tenant<https://learn.microsoft.com/entra/identity-platform/quickstart-register-app>.\n When you add an application to a Microsoft Entra tenant, you must specify the following information:\n Setting|Description\n Name|Specify a unique name for your application.\n Supported account types|Select either Accounts in this organizational directory only (Microsoft only - Single tenant) or Accounts in any organizational directory (Any Microsoft Entra ID directory - Multitenant).\n Redirect URI|(optional) This setting is only required if you want to use the Business Central web client to grant consent to the API (see task 2). Otherwise, you can grant consent using the Azure portal.<br><br>To specify the redirect URL, set the first box to Web to specify a web application. Then, enter the URL for your Business Central on-premises browser client, followed by OAuthLanding.htm, for example: `https://MyServer/BCnnn/OAuthLanding.htm` or `https://cronus.onmicrosoft.com/BCnnn/OAuthLanding.htm`, where BCnnnis the web server instance name, like BC260. This file is used to manage the exchange of data between Business Central and other services through Microsoft Entra ID.<br> <br>Important: The URL must match the URL of Web client, as it appears in the browser address. For example, even though the actual URL might be `https://MyServer:443/BCNNN/OAuthLanding.htm`, the browser typically removes the port number `:443`.\n When completed, an Overview displays in the portal for the new application.\n> NOTE\n> Copy the Application (client) ID of the registered application. You need this value later. You can get this value from the Overview page.\n3. Create a client secret for the registered application as follows:\n 1. Select Certificates & secrets > New client secret.\n 2. Add a description, select a duration, and select Add.\n> NOTE\n> Copy the secret's value for use in your client application code. This secret value is never displayed again after you leave this page.\nLearn more about in Add a client secret<https://learn.microsoft.com/entra/identity-platform/how-to-add-credentials?tabs=client-secret> in the Microsoft Entra documentation.\n4. Grant the registered application API.ReadWrite.All and Automation.ReadWrite.All permission to the Dynamics 365 Business Central API as follows:\n 1. Select API permissions > Add a permission > Microsoft APIs.\n 2. Select Dynamics 365 Business Central.\n 3. Select Application permissions, select API.ReadWrite.All and Automation.ReadWrite.All, then select Add permissions.\n  The API permissions page includes one of the following entries:\n  API / Permission name|Type|Description\n  Dynamics 365 Business Central / Automation.ReadWrite.All|Application|Full access to automation\n  Dynamics 365 Business Central / API.ReadWrite.All|Application|Access to APIs and webservices\n  See https://learn.microsoft.com/entra/identity-platform/quickstart-configure-app-access-web-apis#add-permissions-to-access-your-web-api.\n 4. (optional) Grant admin consent on each permission by selecting it in the list, then selecting Grant admin consent for \\<tenant name\\>.\n  This step isn't required if you're granting consent from the Business Central web client in task 2.\n## Task 2: Set up the Microsoft Entra application in Business Central\nComplete these steps to set up the Microsoft Entra application for service-to-service authentication in Business Central.\n1. In the Business Central client, search for Microsoft Entra applications and open the page.\n2. Select New.\n The Microsoft Entra application Card opens.\n3. In the Client ID field, enter the Application (Client) ID for the registered application in Microsoft Entra ID from task 1.\n4. Fill in the Description field. If a partner set up this application, enter sufficient partner-identifying information, so all applications set up by this partner can be tracked in the future if necessary.\n5. Set the State to Enabled.\n6. Assign permissions to objects as needed.\n See Assign Permissions to Users and Groups</ui-define-granular-permissions>.\n> IMPORTANT\n> Applications can't be assigned the SUPER permission set. Make sure that applications follow least-privilege principle and only assign permissions required for the integration to work.\n> NOTE\n> The system permission sets and user groups called D365 AUTOMATION and EXTEN. MGT. - ADMIN provide access to most typical objects used with automation.\n> The EXTEN. MGT. - ADMIN permission set was introduced in Business Central 2021 release wave 1 as a replacement for the D365 EXTENSION MGT permission set in earlier versions.\n7. (optional) Select Grant Consent and follow the wizard.\n This step grants consent to the API. This step is only required if you didn't grant consent from the Azure portal in task 1. You can only complete this step if you configured a redirect URL in the registered Microsoft Entra app.\n> TIP\n> Pre-consent can be done by adding the Microsoft Entra application to the Adminagents group in the partner tenant. See https://learn.microsoft.com/graph/auth-cloudsolutionprovider#pre-consent-your-app-for-all-your-customers in the Graph documentation.\n## Calling API and web services OAuth2Flows\nAfter the Microsoft Entra application is set up and access granted, you're ready to make API and web service calls to Business Central.\nFor most cases, use the AcquireTokenByAuthorizationCode method from the OAuth 2.0 module. See Microsoft identity platform and OAuth 2.0 authorization code flow<https://learn.microsoft.com/entra/identity-platform/v2-oauth2-auth-code-flow>. Explore an example at OAuth2Flows<https://github.com/microsoft/BCTech/blob/master/samples/OAuth2Flows/TestOAuth2Flows.Page.al>.\n> IMPORTANT\n> When getting access tokens, it's important to keep security in mind. For example, ensure that you don't expose the tokens. You can do that in two ways:\n > Make the method you're using non-debuggable. Here's an example of how to use the non-debuggable property for protecting access tokens:\n```\n>    [NonDebuggable]\n>    procedure GetAccessToken(var AccessToken: Text): Boolean\n>    begin\n>        ...\n>    end;\n>\n>```\n>\n>* Set the `showMyCode` property to false for the extension.\n\n> [!TIP]\n> You can also see this sample in the [BCTech GitHub repo](https://github.com/microsoft/BCTech/tree/master/samples/VSCRestClientOAuthBCAccess).\n\nThe following sample uses the [Rest Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) for Visual Studio Code using the Client Credentials OAuth 2.0 flow. Using the Rest Client makes it easy to see which HTTP calls are made both against Business Central and Microsoft Entra ID. Any HTTP client can be used to create the following requests. Or you can choose any library, like MSAL (short for Microsoft Authentication Library). Remember to specify the scope as `https://api.businesscentral.dynamics.com/.default` and the Token URL as `https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/token`.\n\n```http\n@tenantId = <tenant id>\n@clientId = <client id>\n@clientSecret = <client secret>\n@baseUri = https://api.businesscentral.dynamics.com\n@scope = {{baseUri}}/.default\n@bcEnvironmentName = production\n@url = {{baseUri}}/v2.0/{{bcEnvironmentName}}/api/v2.0\n\n### Define entity, like customers, items, or vendors\n@entityName =customers\n\n# @name auth\nPOST https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token HTTP/1.1\nContent-type: application/x-www-form-urlencoded\n\ngrant_type=client_credentials\n&client_id={{clientId}}\n&client_secret={{clientSecret}}\n&scope={{scope}}\n\n### Variable Response\n@accessHeader = Bearer {{auth.response.body.$.access_token}}\n\n# @name GetCompanies\nGET {{url}}/companies HTTP/1.1\nAuthorization: {{accessHeader}}\n\n### Variable Response\n@companyId = {{GetCompanies.response.body.value.[0].id}}\n@companyUrl = {{url}}/companies({{companyId}})\n@displayName = MyItemDisplayName2\n\n### Get entities\n\n# @name GetEntities\nGET {{companyUrl}}/{{entityName}} HTTP/1.1\nAuthorization: {{accessHeader}}\n\n### Create entity\n\n# @name CreateEntity\nPOST {{companyUrl}}/{{entityName}} HTTP/1.1\nContent-Type:  application/json\nAuthorization: {{accessHeader}}\n\n{\n \"displayName\" : \"{{displayName}}\"\n}\n\n### Get created entity\n\n# @name GetCreatedEntity\nGET {{companyUrl}}/{{entityName}}/?$filter=displayName eq '{{displayName}}' HTTP/1.1\nAuthorization: {{accessHeader}}\n\n#### Variable Response\n@entityId = {{GetCreatedEntity.response.body.value.[0].id}}\n\n### Modify entity\n\n# @name ModifyEntity\nPATCH {{companyUrl}}/{{entityName}}({{entityId}})\nAuthorization: {{accessHeader}}\nContent-Type:  application/json\nIf-Match: *\n\n{\n    \"displayName\" : \"DeleteMe-{{displayName}}\"\n}\n\n### Delete entity\n\n# @name DeleteItem\nDelete {{companyUrl}}/{{entityName}}({{entityId}})\nAuthorization: {{accessHeader}}\n```\n## Related information\nOAuth2 and Microsoft Entra ID<https://learn.microsoft.com/azure/active-directory/develop/active-directory-v2-protocols>\nClient Credentials flow/S2S using MSAL library<https://learn.microsoft.com/azure/active-directory/develop/scenario-daemon-overview>\nC# samples using Client Credentials flow<https://github.com/Azure-Samples/active-directory-dotnetcore-daemon-v2>\nOAuth 2.0 client credentials flow on the Microsoft identity platform<https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow>\nSamples and libraries for OAuth: Microsoft identity platform authentication libraries<https://learn.microsoft.com/azure/active-directory/develop/reference-v2-libraries>\nBusiness Central Repository on GitHub - PowerShell samples using MSAL<https://github.com/microsoft/BCTech/tree/master/samples/PSOAuthBCAccess>\nBusiness Central API v2.0<../api-reference/v2.0>"}