{"title":"Protecting sensitive values with the SecretText data type","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-secret-text/","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/devenv-secret-text, 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/devenv-secret-text","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":"The SecretText data type is designed to protect sensitive values from being exposed when debugging.","date":"2025-01-30","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Protecting sensitive values with the SecretText data type","slug":"protecting-sensitive-values-with-the-secrettext-data-type","at":0,"chars":7518},{"level":2,"title":"The lifetime of a credential","slug":"the-lifetime-of-a-credential","at":444,"chars":5568},{"level":3,"title":"Retrieval","slug":"retrieval","at":853,"chars":1586},{"level":3,"title":"Transit","slug":"transit","at":2439,"chars":1121},{"level":3,"title":"Consumption","slug":"consumption","at":3560,"chars":2452},{"level":2,"title":"Built-in methods","slug":"built-in-methods","at":6012,"chars":1352},{"level":3,"title":"The Unwrap method","slug":"the-unwrap-method","at":6208,"chars":404},{"level":3,"title":"The SecretStrSubstNo method","slug":"the-secretstrsubstno-method","at":6612,"chars":752},{"level":2,"title":"Related information","slug":"related-information","at":7364,"chars":154}],"text":"# Protecting sensitive values with the SecretText data type\n> APPLIES TO: Business Central 2023 release wave 2 (version 23) and later\nThe methods-auto/secrettext/secrettext-data-type is designed to protect sensitive values from being exposed through the AL debugger when doing regular or snapshot debugging. Its use is recommended for applications that need to handle any kind of credentials like API keys, custom licensing tokens, or similar.\n## The lifetime of a credential\nWhen a credential isn't protected by the NonDebuggable attribute on a procedure scope or in the variable it's contained in, it's vulnerable to being exposed\nin a debugging session or a snapshot for its entire lifetime in AL code. This lifetime can be split into three distinct phases; retrieval, transit, and consumption. Read more about the three phases in the next sections.\n### Retrieval\nA credential can be retrieved in multiple ways:\n1. An API key is retrieved through a call via the AL HttpClient and then used as authentication for further calls.\n2. A token is fetched through a control add-in implementing an integration with an authentication provider like OAUTH2.\n3. A custom developer defined scenario creates an authentication token.\n4. A developer mistakenly hard-codes a credential in the code for testing purposes and forgets to remove it.\nAny value of type Text or Code can be assigned to a SecretText value. If the tokens are retrieved and then converted to a SecretText value in the scope of a nondebuggable procedure, they're protected from the debugger during their lifetime. Furthermore, the AL compiler guarantees that a hardcoded credential can't be assigned directly to a destination of type SecretText.\n```al\n[NonDebuggable]\nprocedure RetrieveSessionToken(Credential: SecretText; TargetUri: Text) SessionToken : SecretText\nvar\n    Request: HttpRequestMessage;\n    Response: HttpResponseMessage;\n    Client: HttpClient;\n    Headers: HttpHeaders;\n    Content: HttpContent;\nbegin\n    Request.SetRequestUri(TargetUri);\n    Request.GetHeaders(Headers);\n\n    // Compose an authorization header with a secret value\n    Headers.Add('Authorization', SecretStrSubstNo('Bearer %1', Credential));\n    Client.Send(Request, Response);\n\n    ParseSessionToken(Response, SessionToken);\n    exit;\nend;\n\n[NonDebuggable]\nprocedure ParseSessionToken(Response: HttpResponseMessage; var SessionToken: SecretText) : Text\nbegin\n    // Parse the response\nend;\n```\n### Transit\nA credential transits through AL code to reach the points where it's consumed. Transit includes:\n1. Assignment to variables\n2. Use as a parameter to call a procedure/trigger\n3. Becoming the return value of a method call\nThe methods-auto/secrettext/secrettext-data-type guarantees that the value remains nondebuggable by preventing any assignment from itself to any debuggable type. This constraint includes the Variant data type. As a result, the NonDebuggable attribute is only required during retrieval\nand can be omitted for the rest of the lifetime of a credential, as all intermediate destinations are automatically protected.\n```al\nprocedure Assignments()\nvar\n    PlainText: Text;\n    Credential: SecretText;\nbegin\n    Credential := PlainText; // Allowed\n    PlainText := Credential; // Blocked\n\n    ConsumePlainText(PlainText); // Allowed\n    ConsumePlainText(Credential); // Blocked\n\n    Credential := ProduceCredential(); //Allowed\n    PlainText := ProduceCredential(); // Blocked\nend;\n\nprocedure ConsumePlainText(PlainText: Text)\nbegin\nend;\n\nprocedure ProduceCredential(): SecretText\nbegin\nend;\n```\n### Consumption\nFinally, the credential is consumed when it's used to perform an operation. A common example is communicating with an external web service via the AL HttpClient\nwhere the following steps might be required:\n1. Creating an authentication header for the request with the credential.\n2. Adding the credential to the body of a request for the initial sign in.\n3. Adding an API key to the parameters of a request\nThe AL HttpClient and all the intermediate types required to make a request support method, which accepts the SecretText data type, so that the values can be passed directly to the AL runtime without being revealed to the debugger.\nThe following code snippet demonstrates how all the before mentioned scenarios can be implemented through these methods.\n```al\nprocedure SendAuthenticatedRequestToApi(UriTemplate: Text; BearerToken: SecretText; KeyParameter: SecretText; SecretBody: SecretText)\n    var\n        Client: HttpClient;\n        Headers: HttpHeaders;\n        SecretHeader: SecretText;\n        SecretUri: SecretText;\n\n        RequestMessage: HttpRequestMessage;\n    begin\n        SecretHeader := SecretStrSubstNo('Bearer %1', BearerToken);\n\n        RequestMessage.GetHeaders(Headers);\n\n        // The header is added and remains hidden when debugging the headers\n        // of the request message\n        Headers.Add('Authorization', SecretHeader);\n\n        // Headers.Contains('Authorization') - false\n        // Headers.ContainsSecret('Authorization') - true\n        // Headers.GetSecretValues must be used to get the values.\n        // It is not possible to retrieve the header value as a plain text.\n\n        SecretUri := SecretStrSubstNo(UriTemplate, KeyParameter);\n        RequestMessage.SetSecretRequestUri(SecretUri);\n\n        // RequestMessage.GetSecretRequestUri can be used to retrieve the request uri.\n        // It cannot be retrieved by GetRequestUri as a plain text.\n\n        RequestMessage.Content.WriteFrom(SecretBody);\n\n        // RequestMessage.Content.ReadAs can only read back the body in a SecretText destination\n\n        SendMessageAndHandleResponse(Client, RequestMessage);\n    end;\n\n    [NonDebuggable]\n    procedure SendMessageAndHandleResponse(Client: HttpClient; Request: HttpRequestMessage) CredentialFromResponse: SecretText\n    var\n        Response: HttpResponseMessage;\n    begin\n        Client.Send(Request, Response);\n        Response.Content.ReadAs(CredentialFromResponse);\n    end;\n```\n## Built-in methods\nThe SecretText data type provides a set of built-in methods that allow for working with the values in a secure way. The following sections describe the most important methods.\n### The Unwrap method\nThe Unwrap method allows the value to be extracted from a SecretText to a textual destination for compatibility reasons. It's only permitted when building applications for the 'OnPrem' scope and its use produces a warning unless it's called inside a procedure with the NonDebuggable attribute. It's not recommended to use this method for any other use except .NET interoperability.\n### The SecretStrSubstNo method\nThe SecretStrSubstNo method allows for composing different values of type SecretText without revealing their values. Its behavior is identical to the StrSubstNo method on Text values with the important difference that its parameters and return value are of type SecretText.\nSome examples are demonstrated in the following snippet:\n```al\nprocedure SecretStrSubstNoExamples()\nvar\n    First: SecretText;\n    Second: SecretText;\n    Result: SecretText;\nbegin\n    // Concatenation\n    Result := SecretStrSubstNo('%1%2', First, Second);\n\n    // Build a header value\n    Result := SecretStrSubstNo('Bearer %1', First);\n\n    // Build a comma separated value list\n    Result := SecretStrSubstNo('%1,%2', First, Second);\nend;\n```\n## Related information\nmethods-auto/secrettext/secrettext-data-type\nattributes/devenv-nondebuggable-attribute\nmethods-auto/httpclient/httpclient-data-type"}