{"title":"Authentication tools - alauthlogin and alauthlogout","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/al-agent-tools/al-tool-auth/","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/developer/al-agent-tools/al-tool-auth, 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/developer/al-agent-tools/al-tool-auth","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":"Learn about the al_auth_login and al_auth_logout tools available for AL development, including how to use them in Visual Studio Code with GitHub Copilot and through the AL MCP Server for headless environments and CI/CD pipelines.","date":"2026-10-02","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Authentication tools - al_auth_login and al_auth_logout","slug":"authentication-tools---al_auth_login-and-al_auth_logout","at":0,"chars":4230},{"level":2,"title":"al_auth_login","slug":"al_auth_login","at":786,"chars":2136},{"level":3,"title":"Parameters","slug":"parameters","at":1068,"chars":753},{"level":3,"title":"Return value","slug":"return-value","at":1821,"chars":292},{"level":3,"title":"Examples","slug":"examples","at":2113,"chars":497},{"level":3,"title":"When to call al_auth_login","slug":"when-to-call-al_auth_login","at":2610,"chars":312},{"level":2,"title":"al_auth_logout","slug":"al_auth_logout","at":2922,"chars":681},{"level":3,"title":"Parameters","slug":"parameters-1","at":3135,"chars":21},{"level":3,"title":"Return value","slug":"return-value-1","at":3156,"chars":186},{"level":3,"title":"When to call al_auth_logout","slug":"when-to-call-al_auth_logout","at":3342,"chars":261},{"level":2,"title":"Security design","slug":"security-design","at":3603,"chars":278},{"level":2,"title":"Related tools","slug":"related-tools","at":3881,"chars":239},{"level":2,"title":"Related information","slug":"related-information","at":4120,"chars":110}],"text":"# Authentication tools - al_auth_login and al_auth_logout\nApplies to: AL Language extension 17.0 and later | Available in: AL MCP Server only\nTwo tools manage authentication for the AL MCP Server when connecting to Business Central cloud environments (SaaS). Authentication uses browser-based interactive sign-in through Microsoft Authentication Library (MSAL). Tokens are cached securely on disk and reused automatically by tools that require them, such as al_publish and al_downloadsymbols.\n> NOTE\n> These tools are available on the AL MCP Server only. In Visual Studio Code, authentication is handled transparently using the existing Visual Studio Code account session.\n> For on-premises Business Central deployments that use Windows authentication, no explicit sign in is required.\n## al_auth_login\nThe al_auth_login tool opens a browser window for interactive Microsoft Entra ID sign-in. After the user signs in, the resulting token is cached. Subsequent AL MCP tool calls that require authentication uses the cached token automatically, without prompting again.\n### Parameters\nParameter|Type|Default|Description\ntenant|string|`\"common\"`|The Microsoft Entra tenant domain or GUID (for example, `\"contoso.onmicrosoft.com\"` or a GUID). Use `\"common\"` to allow any tenant.\nenvironmentType|string|`\"Sandbox\"`|The type of Business Central environment: `\"OnPrem\"`, `\"Sandbox\"`, or `\"Production\"`.\nenvironmentName|string|-|The name of the cloud environment (for example, `\"sandbox\"` or `\"production\"`).\napplicationFamily|string|-|The application family for the cloud server, if applicable.\nusernameHint|string|-|Optional. Prefills the account selector in the browser sign-in dialog with the specified email address.\nnoCache|boolean|false|When true, clears any existing cached tokens before initiating the new sign-in flow.\n### Return value\nProperty|Type|Description\nSucceeded|boolean|true if authentication completed successfully.\nAuthRequired|boolean|true if user interaction in the browser is required (this is the expected state for an interactive sign in).\nMessage|string|Status message describing the outcome.\n### Examples\nAuthenticate to a sandbox environment:\n```json\n{\n  \"tenant\": \"contoso.onmicrosoft.com\",\n  \"environmentType\": \"Sandbox\",\n  \"environmentName\": \"sandbox\"\n}\n```\nAuthenticate with a username hint (to pre-select an account):\n```json\n{\n  \"tenant\": \"contoso.onmicrosoft.com\",\n  \"environmentType\": \"Production\",\n  \"usernameHint\": \"user@contoso.onmicrosoft.com\"\n}\n```\nForce re-authentication (clear cached tokens first):\n```json\n{\n  \"tenant\": \"contoso.onmicrosoft.com\",\n  \"noCache\": true\n}\n```\n### When to call al_auth_login\n Before calling al_publish with a cloud environment for the first time.\n Before calling al_downloadsymbols with a cloud environment.\n When you receive an authentication error from another tool.\n When switching to a different Microsoft Entra account (combine with `noCache: true`).\n## al_auth_logout\nThe al_auth_logout tool clears all cached Microsoft Entra ID tokens from the local MSAL token cache. After calling this tool, any tool that requires authentication will prompt for sign-in again.\n### Parameters\nNone.\n### Return value\nProperty|Type|Description\nSuccess|boolean|true if the token cache was cleared successfully.\nMessage|string|Confirmation message (for example, `\"Token cache cleared.\"`).\n### When to call al_auth_logout\n To sign out for security purposes after finishing work in a shared or automated environment.\n Before calling al_auth_login with a different account.\n To resolve persistent authentication errors by clearing a stale cached token.\n## Security design\nAuthentication tokens are never passed as tool parameters and are never returned in tool responses. The sign-in flow is handled entirely by MSAL and the user's browser. The AL MCP Server only stores and reuses the resulting token from the secure local cache.\n## Related tools\n al_publish<al-tool-publish> - Deploy an extension; requires authentication for cloud environments.\n al_downloadsymbols<al-tool-download-symbols> - Download symbol packages; requires authentication for cloud environments.\n## Related information\nAI agent tools overview<al-agent-tools-overview>\nAL MCP Server reference<al-mcp-server>"}