Creatio development guide
This documentation is valid for Creatio version 7.16.0. We recommend using the newest version of Creatio documentation.

Authentication of external requests

Glossary Item Box


All external requests to Creatio web services must be authenticated.

We have the following authentication types in Creatio:

  • Anonymous authentication
  • Basic authentication
  • Forms authentication (Cookie based)

The “Forms authentication” is a best practice for integration with the application.

To perform the “Forms authentication”, Creatio uses a separate “AuthService.svc” web service.

Starting with version 7.10, authentication is protected from CSRF attacks.

CSRF (Cross Site Request Forgery) – is a type of attacks for web site visitors based on possible HTTP problems.

You need to perform authentication using the “AuthService.svc” service when integrating with third party applications. After you successfully authenticate, AuthService returns the authentic cookie that must be added to your request. It also returns a cookie containing the CSRF token. This token must be placed in the request header. You can find examples of an authentic cookie below and in the "Integration via OData protocol" and "DataService” articles.

AuthService.svc request

Example of an authentication HTTP request
POST /ServiceModel/AuthService.svc/Login HTTP/1.1
Content-Type: application/json
ForceUseSession: true

Web service request structure:

  • query string;
  • request headers;
  • request body.

Query string

To perform authentication, call the “Login “ AuthService.svc. method.

Query string structure

http(s)://[Creatio application address]/ServiceModel/AuthService.svc/Login

Example of a query string

Request headers

Content-Type: application/json
Encoding and resource type passed in the request body.
ForceUseSession: true
The “ForceUseSession” header accounts for using the existing session.

Request body

The request body must pass the Creatio user credentials. The credentials are passed as a JSON object.

Properties of the JSON object with credentials

The user name of a Creatio user.
The password of a Creatio user.

Example of a request body:


AuthService.svc response

Structural elements of the request response:

  • HTTP status code;
  • response headers;
  • response body.

HTTP status code

As a request response, the server returns an HTTP status code encrypted in 3 digits. The first digit specifies the status class. The second and the third digits determine the response ordinal number.

When executing the authentication request, the server returns the following status codes:

200 OK  The request has been completed sucessfully and the resource value is not equal to zero. In this case, the request body should contain the authentication status code. If it contains 0, the authentication is successful. In case of unsuccessful authentication, the authentication status code will equal 1 and the request body will contain a message about the cause of the unsuccessful authentication.  
403 Forbidden  The server cannot provide access to the resource specified in the request (for example, if a method name is spelled incorrectly). Request body can contain additional information.  

Response headers

The response to a POST request contains authentication cookies. You need to save these cookies on the side of the client or on the client computer to use them in your further Creatio web service queries.

Response body

Example of an authentication service response
 "Code": 0,
 "Message": "",
 "Exception": null,
 "PasswordChangeUrl": null,
 "RedirectUrl": null

The response body will contain a JSON object of the authentication status.

The primary properties of the JSON object:

Authentication status code
If the code contains a “0” value, the authentication is successful. Othewise, it is failed.
The message notifying of an unsuccessful authentication.
The object that contains a detailed description of the exception connected with the unsuccessful authentication.

Example of a software implementation of the authentication

Create a C# console application in Visual Studio and give it a name, e.g., RequestAuthentification. You can download the full code with case implementation using the following link.

Example of a software implementation of the authentication
// Sends a request to the authentication service and processes the response.
public void TryLogin() {
    var authData = @"{
        ""UserName"":""" + _userName + @""",
        ""UserPassword"":""" + _userPassword + @"""
    var request = CreateRequest(_authServiceUrl, authData);
    _authCookie = new CookieContainer();
    request.CookieContainer = _authCookie;
    // Upon successful authentication, we save authentication cookies for
    // further use in requests to Creatio. In case of failure
    // authentication application console displays a message about the reason
    // of the mistake.
    using (var response = (HttpWebResponse)request.GetResponse())
        if (response.StatusCode == HttpStatusCode.OK)
            using (var reader = new StreamReader(response.GetResponseStream()))
                var responseMessage = reader.ReadToEnd();
                if (responseMessage.Contains("\"Code\":1"))
                    throw new UnauthorizedAccessException($"Unauthorized {_userName} for {_appUrl}");
            string authName = ".ASPXAUTH";
            string authCookeValue = response.Cookies[authName].Value;
            _authCookie.Add(new Uri(_appUrl), new Cookie(authName, authCookeValue));
// Create request to the authentication service.
private HttpWebRequest CreateRequest(string url, string requestData = null)
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
            request.ContentType = "application/json";
            request.Method = "POST";
            request.KeepAlive = true;
            if (!string.IsNullOrEmpty(requestData))
                using (var requestStream = request.GetRequestStream())
                    using (var writer = new StreamWriter(requestStream))
            return request;
// Method realizes protection from CSRF attacks: copies cookie, which contents CSRF-token 
// and pass it to the header of the next request.
private void AddCsrfToken(HttpWebRequest request) {
    var cookie = request.CookieContainer.GetCookies(new Uri(_appUrl))["BPMCSRF"];
    if (cookie != null) {
        request.Headers.Add("BPMCSRF", cookie.Value);

Disabling the CSRF protection

We recommend disabling the CSRF protection only if you use basic authentication.

In Creatio, you can disable the CSRF protection both for the whole application or for separate services and methods.

  1. Disabling the CSRF protection for all application services
    In the .\Web.Config and .\Terrasoft.WebApp\Web.Config files, disable the UseCsrfToken setting:
    <add value="false" key="UseCsrfToken" />
  2. Disabling the CSRF protection for one application service
    Use the DisableCsrfTokenValidationForPaths setting in the .\Web.Config file:
    <add key="DisableCsrfTokenValidationForPaths" value="/ServiceModel/ MsgUtilService.svc" />
  3. Disabling the CSRF protection for several methods of different services
    You can do it using the same DisableCsrfTokenValidationForPaths setting in the .\Web.Config file.
    <add key="DisableCsrfTokenValidationForPaths" value="/MsgUtilService.svc/Ping,/AuthService.svc/Login" />


© Creatio 2002-2020.

Did you find this information useful?

How can we improve it?