API and Authentication
  • 15 Mar 2024
  • 2 Minutes to read
  • Dark

API and Authentication

  • Dark

Article summary

The most common use case of the Decisions API is running Rules and Flows through a Rest Service call. However, the API can be used for other functions such as provisioning users, setting up folders or projects, setting branding, and more.

Authenticating to Decisions API

There are two primary ways to authenticate to Decisions API; using the authentication information provided by the View Integration Details page or providing authentication information in the HTTP Header.

Authentication information is required to call Decisions via API. This allows Decisions to grant access, check authorizations for specific activities, govern access to specific data, and audit the actions taken in the product.

Calling methods without the proper authentication information results in a 403, Forbidden Error.

View Integrations Details Page

The View Integrations Details page allows users to set parameters and obtain the appropriate GET or POST request types to execute a task. 

Request TypeDescription
GETAuthentication information is provided in the request URL
POSTAuthentication information is included as part of the POST body

Request Header Authentication

Users have the option to add authentication information in the Request Header. By using this option, users do not need to provide the authentication information in the URL or POST body. Instead, provide the information in the Request Header's Authorization field option.

 The Header values for the request will be different based on the type of authorization type.

Authorization TypeInput PassedExample Header
BasicUsername and Password encoded string (Base 64 Encode of "username:password", e.g., Base 64 encode of 'admin@decisions.com:admin') combined with a colon character"Authorization":"Basic YWRtaW5AZGVjaXNpb25zLmNvbTphZG1pbg=="
SessionSessionID or NamedSessionID"Authorization":"Session {SessionID or Named Session ID}"
BearerJWT Token"Authorization":"Bearer {JWTTOKEN}"

Basic Authorization Type

Username and Password are passed to the services as a Basic Authorization and should only be used for simple, periodic API calls. In most API uses, the username and password are used to create a Session for subsequent calls.

To programmatically send the User id and Password, combine them with a colon (:) character and then base64 encode the result. This is placed in the Header with the Basic’ keyword.

string merged = $"{userName}:{userPassword}";
string toSend = Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(merged));
HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Basic", toSend));

Session Authorization Type

A SessionID will be returned by utilizing the following API call. 

Post Body: { "outputtype" : "Json" }
Http Header: Authorization: Basic (Base64 String as described above)

Bearer Authorization Type

The Bearer Authorization Type requires a JWT Token. 

Get the JWT Token with a username and password via the POST method.

Post Body: {
  "userName": "username",
  "password": "password",
  "outputtype": "Json"

Once the JWT token has been acquired, API calls can be achieved by using the Bearer Authorization Type. 

URL: http://[portalbaseURL]/Primary/?[DesignerElement]ID=[DesignerElementIDValue]&Action=api&outputtype=JSON

Http Header: Authorization: Bearer (JWT token)

Request Cookies on API Calls

On API calls, Decisions uses the following headers and cookies: 

Cookie NameDescription
Decisions.AuthAllows a user to stay logged in after authentication
SessionValuePassed in on calls to connect actions to an account
ClientEventSessionIdUnique ID to each open tab of Decisions (not the same as the SessionID)
formSessionInfoIdID related to the currently running Form

For further information on Integrations, visit the Decisions Forum.

Was this article helpful?