REST API

Implementation Guide

9.2.0 Release
Copyright © 2025 OneStream Software LLC. All rights reserved.

All trademarks, logos, and brand names used on this website are the property of their respective
owners. This document and its contents are the exclusive property of OneStream Software LLC
and are protected under international intellectual property laws. Any reproduction, modification,
distribution or public display of this documentation, in whole or part, without written prior consent
from OneStream Software LLC is strictly prohibited.
Table of Contents

Table of Contents
Introduction 1

REST API Summary 2

Version 5.2.0 2

Authentication 2

DataManagement 2

DataProvider 3

Version 7.2.0 3

Authentication 3

Application 3

DataManagement 4

DataProvider 4

REST API Overview 5

OneStream Web API Endpoints 5

Authentication 5

REST API Implementation Guide i

Table of Contents

DataManagement 5

DataProvider 6

Call State For Long Running Requests 7

Authentication 8

Application API 10

Data Provider API v7.2.0 12

OneStream REST API Implementation 15

Authentication 15

OneStream WebAPI Endpoints 18

Configure OneStream API for External Authentication 40

Azure AD (Microsoft Entra ID) Configuration 40

Configure the REST API Application Registration in Azure AD

(Microsoft Entra ID) 41

Set Up the Web Server Configuration in OneStream 42

Configure the User in OneStream 45

Azure AD (Microsoft Entra ID) Endpoints 46

REST API Implementation Guide ii

Table of Contents

Set Up Postman Access Token Requests 47

Okta Configuration 48

Configure the REST API Application Registration in Okta 49

Add Authorization Servers and Scopes in Okta 49

Set Up the Web Server Configuration in OneStream 50

Configure the User in OneStream 53

PingFederate Configuration 53

Configure the REST API Application Registration in

PingFederate 54

Set Up the Web Server Configuration in OneStream 54

Configure the User in OneStream 57

Configure the AUD Value 58

REST API Implementation Guide iii

Introduction

Introduction
This guide provides information about the implementation, authentication, and application
programming interfaces available to extend OneStream functionality.

OneStream Web API is a RESTful web service designed to expose OneStream Data Automation
functions when interacting with third-party API client applications.

For customers in a self-hosted environment, Web API must be installed on a web server and
configured for external authentication providers supporting OAuth2.0/OpenID Connect
authorization protocol. Identity providers currently supported are Azure AD (Microsoft Entra ID),
Okta, and PingFederate.

All customers in a OneStream-hosted environment using authentication with OneStream

IdentityServer, including those using native authentication and any OIDC or SAML 2.0 compliant
external identity providers, must use personal access tokens (PATs) to access OneStream REST
API.

To maintain optimal performance and ensure security, use public and documented APIs only.
Internal APIs are not intended for public general use and may be changed or removed without
notice. Support cannot provide assistance for issues resulting from the uses of nonpublic
features.

See the Identity and Access Management Guide for information about authentication with
OneStream IdentityServer and using PATs.

OneStream Web API is API client agnostic. It accepts and outputs data in JSON format making it
possible for every API client application that supports this format to also interact with the service.

REST API Implementation Guide 1

REST API Summary

REST API Summary

Version 5.2.0
In version 5.2.0 of OneStream REST API, all the API calls are synchronous. The responses do not
come back until all the data has been processed on the OneStream server. It is not recommended
to use this version for large datasets because timeouts may occur before the response comes
through. For large datasets, it is recommended to use the asynchronous API endpoints
introduced in version 7.2.0.

Authentication
Typically, this API is used only to verify that the REST API is configured correctly and the token
used to authenticate is valid. In this version, after the configuration and token have been validated
for authentication, it is not necessary to call this API for other APIs to function as long as a proper
authentication token is provided on those API calls.

DataManagement
This API is used to run sequences and steps on the OneStream servers. This can be used to run
consolidations, business rules, or any other types of sequences and steps configured in
OneStream. The API calls in this version do not respond with a success or failure status until after
the task has completed in OneStream, which can take a long time in some cases.

REST API Implementation Guide 2

REST API Summary

DataProvider
This API is used to return data from within OneStream to a third-party application or script. It can
be used to return data from a OneStream-configured data adapter, Cube View, SQL query, or
method command. If the API call is successful, the data is returned in JSON format within the
response body. If the dataset is large, it may take a long time for the response to come back.

Version 7.2.0
In version 7.2.0 of OneStream REST API, the API calls are both synchronous and asynchronous.
The asynchronous calls are recommended for large datasets or when an immediate response is
needed.

Authentication
This API contains only the Logon API call, which is necessary to return the SessionInfo (SI) object
for use within any other API calls in this version.

Application
This API contains only the OpenApplication API call and returns a SessionInfo object for a specific
application. This is necessary when making any other API call that requires an open application,
which is almost always the case. It requires the SessionInfo token from the Logon API call as a
parameter within the body of the request.

REST API Implementation Guide 3

REST API Summary

DataManagement
This API is used to run sequences and steps on the OneStream servers. This can be used to run
consolidations, business rules, or any other types of sequences and steps configured in
OneStream.

In this version of the DataManagement API, the ExecuteSequence and ExecuteStep API calls
have been consolidated into a single endpoint where a parameter specifies whether it is calling a
sequence or a step. It also contains an asynchronous endpoint where the response is issued
immediately instead of waiting for the sequence or step to complete. This can be helpful if the step
or sequence typically takes a long time to run. There is also an API call to check the status of the
step or sequence that was initiated. This can be used in a client-side polling and sleep loop to wait
for the task to be completed. All calls within this API run against a specific application and
therefore require a SessionInfo object from OpenApplication.

DataProvider
The API calls in this section are used to return data from within OneStream to a third-party
application or script. In this version, it can only be used to return data from a OneStream-
configured data adapter. However, the data adapter itself can receive data from a variety of
different types of sources. There is also both a synchronous and asynchronous version of the API
call. Developers can decide whether they want the call to block and wait until the data is
processed and delivered or they want to use client-side polling and sleep loop to wait for the data
to be available, which requires that XFCallState is enabled in the configuration. The latter option
may be preferable when expecting large sets of data or when there are a lot of calculations
involved, which may slow down delivery to a point where a timeout may occur.

REST API Implementation Guide 4

REST API Overview

REST API Overview

In this topic:

l OneStream Web API Endpoints

l OneStream REST API Implementation

l Configure OneStream API for External Authentication

OneStream Web API Endpoints

URLs are relative to query parameter api-version=5.2.0, unless otherwise noted.

Authentication
Authentication endpoint. Represents a RESTful service for Authentication.

l POST api/Authentication/LogonAndReturnCookie

Used primarily to verify Web API installation completed successfully. Returns an

authentication message or a message indicating failure along with a proper HTTP code.

DataManagement
DataManagement endpoint. Represents a RESTful service of Data Management.

l POST api/DataManagement/ExecuteSequence:

Executes a Data Management Sequence and returns a success/failure message along with
a proper HTTP code.

REST API Implementation Guide 5

REST API Overview

l POST api/DataManagement/ExecuteStep

Executes a Data management Step and returns a success/failure message along with a
proper HTTP code.

DataProvider
DataProvider endpoint represents a RESTful service of Data Provider.

l POST api/DataProvider/GetAdoDataSetForAdapter:

Executes a Data Provider HTTP Post request and returns a JSON representation of a
DataSet for a given Dashboard Adapter.

l POST api/DataProvider/GetAdoDataSetForCubeViewCommand

Executes a Data Provider HTTP Post request and returns a JSON representation of a
DataSet for a given Cube View.

l POST api/DataProvider/GetAdoDataSetForSqlCommand

Executes a Data Provider HTTP Post request and returns a JSON representation of a
DataSet for a given Sql query. Administrator role is required for this functionality.

l POST api/DataProvider/GetAdoDataSetForMethodCommand

Executes a Data Provider HTTP Post request and returns a JSON representation of a
DataSet for a given pre-defined list of method commands. Administrator role is required
for this functionality.

REST API Implementation Guide 6

REST API Overview

Call State For Long Running Requests

To prevent proxy appliance time-out, a polling method was introduced for long running requests.
When this is enabled, all requests use the polling method based on the configured setting in the
[Link] indicating how long the request has to complete. This allows long
running requests to complete without the proxy appliances returning a 502 Bad Gateway as a
response to the request inactivity that causes the proxy to terminate the connection.

How It Works
XFCallState polling must first be enabled in the [Link] in the
EnvironmentSettings block.

The configured values of UseCallStateForLongRunningRequests and

CallStateNetworkTimeoutNumSeconds manage the XFCallState functionality. When
UseCallStateForLongRunningRequests is set to true, call state polling is used. The configured
value for CallStateNetworkTimeoutNumSeconds determines the time to wait before using call
state to complete the request, default 120 seconds.

REST API Implementation Guide 7

REST API Overview

Authentication
For customers in a OneStream-hosted environment, see the Identity and Access Management
Guide for information about authentication with OneStream IdentityServer and using personal
access tokens (PATs).

To secure REST API with OAuth 2.0 for customers in a self-hosted environment, configure
authentication with one of these supported external providers:

l Azure AD (Microsoft Entra ID) Configuration

l Okta Configuration

l PingFederate Configuration

Access tokens from the any of the above providers have short expiration times. To avoid copying
the entire token value to the Authorization/Token text box, create a variable that holds the value.
For every call to the external provider, the value of the access token returned will be copied to the
variable.

l Create a global variable in Postman, name it appropriately, for instance webapi_access_

token.

l In the Tests tab of the POST request to the external provider copy the script below:

var data = [Link]();

[Link]("webapi_access_token", data.access_token);

Authentication API
Method Endpoint Description

Logs on and returns a SessionInfo

Post Authentication/Logon (SI) object for use with other Rest
API calls that accept an SI as an

REST API Implementation Guide 8

REST API Overview

Method Endpoint Description

argument. This endpoint performs a

logon only and does not open an
application. This is the equivalent of
entering login credentials in the
Desktop App before selecting and
opening an application.

Authentication/Logon

POST [Link]

Query Parameters

Key Value Required

api-version 7.2.0 Yes

Authorization

Type Value Required

Bearer Token (your access token) Yes

Headers

Key Value Required

Content-Type application/json Yes

Request Body

Key Type Description Required

BaseWebServerURL string Your URL for the web service Yes

REST API Implementation Guide 9

REST API Overview

Sample Request

{
"BaseWebServerUrl": "https:// [Link]/OneStreamWeb"
}

Sample Response

{
"Message": "Logon succeeded.",
"Logon SessionInfo": {
"XfBytes": " QB8AACNodHRwOi8vbG9jYWxob3N0OjUwMDAxL09uZVN0cm
VhbVdlYhQAAAB7izp1jCP3BUVr8bjD2f6KmmL5BKzhOVWUzU1MikEYOVekO
ZUIT0tUQV9NMk27tnn6+VZaR544CKlYPCFeWSBWCTmQ2ggAAAAAAAAAAAAA
AAAAAAAAAAAAAAAFZW4tVVMAAAAAAAAAAAAAAAAAAAAAAAAAAP/////////
/////////////////8P//////////////AwAAABn8//8Z/P//Gfz//xn8//
8Z/P//Gfz//xn8//8Z/P//Gfz//xn8//8Z/P//Gfz//w==""
},
"Authorized applications": [
"GolfStreamDemo_2022",
"OFC_ECA_ProductMgmt",
"OneStream_GolfStream"
]
}

Application API
Method Endpoint Description

Opens specified application.

Requires a valid sessionInfo token
Post Application/OpenApplication
obtained from the
Authentication/Logon method.

Application/OpenApplication

POST [Link]
version=7.2.0

REST API Implementation Guide 10

REST API Overview

Query Parameters

Key Value Required

api-version 7.2.0 Yes

Authorization

Type Value Required

Bearer Token (your access token) Yes

Headers

Key Value Required

Content-Type application/json Yes

Request Body

Key Type Description Required

ApplicationName string Name of the application to open Yes

array The SessionInfo (SI) object obtained

SI Yes
(bytes) from Authentication/Logon endpoint.

Sample Request

{
"ApplicationName": "GolfStreamDemo_2022",
"SI": {
"XfBytes": "QB8AACNodHRwOi8vbG9jYWxob3N0OjUwMDAxL09uZVN0cmVhb
VdlYhQAAAB7izp1jCP3BUVr8bjD2f6KmmL5BKzhOVWUzU1MikEYOVekOZUIT0
tUQV9NMk27tnn6+VZaR544CKlYPCFeWSBWCTmQ2ggAAAAAAAAAAAAAAAAAAAA
AAAAAAAAFZW4tVVMAAAAAAAAAAAAAAAAAAAAAAAAAAP//////////////////
////////8P//////////////AwAAABn8//8Z/P//Gfz//xn8//8Z/P//Gfz//
xn8//8Z/P//Gfz//xn8//8Z/P//Gfz//w=="
}
}

REST API Implementation Guide 11

REST API Overview

Sample Response

{
"Message": "Open application succeeded.",
"Application SessionInfo": {
"XfBytes": "QB8AACNodHRwOi8vbG9jYWxob3N0OjUwMDAxL09uZVN0
cmVhbVdlYhQAAAAep0GewgsakcN4GJDmuwyaaIMazfN/aHyhnXNLgg+h
Uxy6cpQIT0tUQV9NMk27tnn6+VZaR544CKlYPCFe0BusL1iM2ggUAAAA
rL9Q04ePExHJxVU89Y1MAeNxrh8UT25lU3RyZWFtX0dvbGZTdHJlYW3x
ShfEXWxvRbOx2hWDSCd0BWVuLVVTAAAAAAAAAAAAAAAAAAAAAAAAAAD/
/////////wAAAAACAFABAABQAfD///8AAAAAYHzddwMAAABCAfAAGfz/
/5z///+c////FQAQACYAIAARAGAAAwCQABn8//8Z/P//Gfz//xn8//8="
}
}

Data Provider API v7.2.0

Method Endpoint Description

Executes a Data Provider HTTP

Post request and and returns a
JSON representation of a DataSet
DataProvider/ for a given Dashboard Adapter.
Post
GetadoDataSetForAdapter Requires a SessionInfo (SI) object
obtained from
Application/OpenApplication
endpoint.

DataProvider/GetAdoDataSetForAdapter

POST https://
{BaseWebServer}/Onestreamapi/api/DataProvider/GetAdoDataSetForAdapter?api-
version=7.2.0

REST API Implementation Guide 12

REST API Overview

Query Parameters

Key Value Required

api-version 7.2.0 Yes

Authorization

Type Value Required

Bearer Token (your access token) Yes

Headers

Key Value Required

Content-Type application/json Yes

Request Body

Key Type Description Required

An indication of whether the

Dashboard Adapter is defined at the
IsSystemLevel boolean Yes
System Level (True) or for the
specified Application (False).

The name of the Dashboard Adapter

AdapterName string Yes
used for data retrieval.

Name of the resulting table in the

ResultDataTableName string Yes
DataSet

Comma separated list of Variable

name/value pairs requiring a user
CustomSubstVarsAsCommaSeparatedPairs string prompt. These must be specified No
using the following format:
"VariableName1=

REST API Implementation Guide 13

REST API Overview

Key Type Description Required

[VariableValue1],VariableName2=
[VariableValue2],...".

The SessionInfo (SI) object obtained

array
SI from Application/OpenApplication Yes
(bytes)
endpoint.

Sample Request

{
"IsSystemLevel": true,
"AdapterName": "Sales Mix (WF)",
"ResultDataTableName": "ResultsTable",
"CustomSubstVarsAsCommaSeparatedPairs": "",
"SI": {
"XfBytes": " QB8AACNodHRwOi8vbG9jYWxob3N0OjUwMDAxL09uZVN0cm
VhbVdlYhQAAAAep0GewgsakcN4GJDmuwyaaIMazfN/aHyhnXNLgg+hUxy6c
pQIT0tUQV9NMk27tnn6+VZaR544CKlYPCFe0BusL1iM2ggUAAAArL9Q04eP
ExHJxVU89Y1MAeNxrh8UT25lU3RyZWFtX0dvbGZTdHJlYW3xShfEXWxvRbO
x2hWDSCd0BWVuLVVTAAAAAAAAAAAAAAAAAAAAAAAAAAD//////////wAAAA
ACAFABAABQAfD///8AAAAAYHzddwMAAABCAfAAGfz//5z///+c////FQAQA
CYAIAARAGAAAwCQABn8//8Z/P//Gfz//xn8//8="
}
}

Sample Response

{
"ResultsTable": [
{
"RowId": 0,
"RowName": "Row1",
"PovCubeNameAndDesc": "GolfStream - Corporate",
"Pov00EntityNameAndDesc": "Total GolfStream",
"Pov02ScenarioNameAndDesc": "Actual - Actual",
"Pov03TimeNameAndDesc": "2011M2 - Feb 2011",
"Pov04ViewNameAndDesc": "YTD",
"RowHdr0NameAndDesc": "Drivers",
"RowHdr0Indent": 0,
"Col0Hdr0NameAndDesc": "60000 - Operating Sales",
"Col0Hdr0Indent": 0,
"Col0Value": 25552270.482000000000000000,
"Col0ValueAsText": "25,552,270.48"

REST API Implementation Guide 14

REST API Overview

},
}
"RowId": 1,
"RowName": "Row1",
"PovCubeNameAndDesc": "GolfStream - Corporate",
"Pov00EntityNameAndDesc": "Total GolfStream",
"Pov02ScenarioNameAndDesc": "Actual - Actual",
"Pov03TimeNameAndDesc": "2011M2 - Feb 2011",
"Pov04ViewNameAndDesc": "YTD",
"RowHdr0NameAndDesc": "Fairway Woods",
"RowHdr0Indent": 0,
"Col0Hdr0NameAndDesc": "60000 - Operating Sales",
"Col0Hdr0Indent": 0,
"Col0Value": 17476089.966000000000000000,
"Col0ValueAsText": "17,476,089.97"
}
]
}

OneStream REST API Implementation

In this topic:

l Authentication

l OneStream WebAPI Endpoints

Authentication
For customers in a OneStream-hosted environment, see the Identity and Access Management
Guide for information about authentication with OneStream IdentityServer and using personal
access tokens (PATs).

To secure REST API with OAuth 2.0 for customers in a self-hosted environment, configure
authentication with one of these supported external providers:

REST API Implementation Guide 15

REST API Overview

l Azure AD (Microsoft Entra ID) Configuration

l Okta Configuration

l PingFederate Configuration

Access tokens from the any of the above providers have short expiration times. To avoid copying
the entire token value to the Authorization/Token text box, create a variable that holds the value.
For every call to the external provider, the value of the access token returned will be copied to the
variable.

l Create a global variable in Postman, name it appropriately, for instance webapi_access_

token.

l In the Tests tab of the POST request to the external provider copy the script below:

var data = [Link]();

[Link]("webapi_access_token", data.access_token);

Authentication API
Method Endpoint Description

Logs on and returns a SessionInfo

(SI) object for use with other Rest
API calls that accept an SI as an
argument. This endpoint performs a
Post Authentication/Logon logon only and does not open an
application. This is the equivalent of
entering login credentials in the
Desktop App before selecting and
opening an application.

REST API Implementation Guide 16

REST API Overview

Authentication/Logon

POST [Link]

Query Parameters

Key Value Required

api-version 7.2.0 Yes

Authorization

Type Value Required

Bearer Token (your access token) Yes

Headers

Key Value Required

Content-Type application/json Yes

Request Body

Key Type Description Required

BaseWebServerURL string Your URL for the web service Yes

Sample Request

{
"BaseWebServerUrl": "https:// [Link]/OneStreamWeb"
}

Sample Response

{
"Message": "Logon succeeded.",
"Logon SessionInfo": {
"XfBytes": " QB8AACNodHRwOi8vbG9jYWxob3N0OjUwMDAxL09uZVN0cm
VhbVdlYhQAAAB7izp1jCP3BUVr8bjD2f6KmmL5BKzhOVWUzU1MikEYOVekO

REST API Implementation Guide 17

REST API Overview

ZUIT0tUQV9NMk27tnn6+VZaR544CKlYPCFeWSBWCTmQ2ggAAAAAAAAAAAAA
AAAAAAAAAAAAAAAFZW4tVVMAAAAAAAAAAAAAAAAAAAAAAAAAAP/////////
/////////////////8P//////////////AwAAABn8//8Z/P//Gfz//xn8//
8Z/P//Gfz//xn8//8Z/P//Gfz//xn8//8Z/P//Gfz//w==""
},
"Authorized applications": [
"GolfStreamDemo_2022",
"OFC_ECA_ProductMgmt",
"OneStream_GolfStream"
]
}

OneStream WebAPI Endpoints

This API implementation is client agnostic therefore every API test capable third-party tool can be
pointed to OneStreamWeb API endpoints. This tutorial is using Postman. Note that all arguments
in the body are required unless otherwise specified.

Versioning This implementation will start with Api-version=5.2.0

Data Management Execute Sequence endpoint

1. Create new POST request in Postman,

2. Url= http(s)://[servername]:
[port]/onestreamapi/api/DataManagement/ExecuteSequence?api-version=5.2.0

3. Authorization: Type=Bearer Token. Token={{webapi_access_token}}

4. Headers: Content-Type=application/json

5. Body (raw / jSON):

{
"BaseWebServerUrl": [OneStream Server Logon URL],

REST API Implementation Guide 18

REST API Overview

"WorkspaceName": [your workspace name], - Optional

"ApplicationName":[your application name],
"SequenceName": [existing sequence name],
"CustomSubstVarsAsCommaSeparatedPairs": [comma separated list of key value
pairs as substitution variables with the following format: "VariableName1=
[VariableValue1],VariableName2=[VariableValue2],..."] - Optional
}

6. Click Send and observe the response at the bottom pane. If successful, a message of "Data
Management Sequence [sequence name] was completed" will be returned otherwise a
descriptive error message will show. More details will be logged in the Error and Activity
logs.

Data Management Execute Step endpoint

1. Create new POST request in Postman,

2. Url= http(s)://[servername]:[port]/onestreamapi/api/DataManagement/ExecuteStep?api-
version=5.2.0

3. Authorization: Type=Bearer Token. Token={{webapi_access_token}}

4. Headers: Content-Type=application/json

5. Body (raw / jSON):

{
"BaseWebServerUrl": [OneStream Server Logon URL],
"ApplicationName":[your application name],
"DataManagementGroupName": [an existing data management group name],
"StepName": [existing step name],
"CustomSubstVarsAsCommaSeparatedPairs": [comma separated list of key value pairs as
substitution variables with the
following format: "VariableName1=[VariableValue1],VariableName2=[VariableValue2],..."] -
Optional
}

REST API Implementation Guide 19

REST API Overview

6. Click Send and observe the response at the bottom pane. If successful, a message of "Data
Management Step [step name] was completed" will be returned otherwise a descriptive
error message will show. More details will be logged in the Error and Activity logs.

REST API Implementation Guide 20

REST API Overview

Data ProviderGetAdoDataSetForAdapter endpoint

1. Create new POST request in Postman,

2. Url= http(s)://[servername]:
[port]/onestreamapi/api/DataProvider/GetAdoDataSetForAdapter?api-version=5.2.0

3. Authorization: Type=Bearer Token. Token={{webapi_access_token}}

4. Headers: Content-Type=application/json

5. Body (raw / jSON):

{
"BaseWebServerUrl": [OneStream Server Logon URL],
"ApplicationName":[your application name],
"WorkspaceName": Reserved for future use. Use an empty string. - Optional,
"AdapterName": [existing adapter name],

"ResultDataTableName": [name of resulting table in the DataSet],

"CustomSubstVarsAsCommaSeparatedPairs": [comma separated list of key value pairs as

substitution variables with the
following format: "VariableName1=[VariableValue1],VariableName2=[VariableValue2],..."] -
Optional
}

Example:

"BaseWebServerUrl": "[Link]

"ApplicationName": "GolfStream_v37",

"IsSystemLevel": "False",

"AdapterName": "ActivityClassListing_PLP",

"ResultDataTableName": "ResultsTable",

"CustomSubstVarsAsCommaSeparatedPairs": ""

REST API Implementation Guide 21

REST API Overview

6. Click Send and observe the response at the bottom pane. If successful, a JSON data table
will be returned otherwise a descriptive error message will show. More details will be logged
in the Error and Activity logs.

This is a returned response from the request using the above body example in Postman:

"ResultsTable": [

"ClassID": "100_Salary",

"Name": "100 - Salary",

"Description": "100 - Salary",

"ValueType": 0,

"ValueTypeName": "Wage Percentage",

"ClassItemID": "79b612b9-8cb4-49ca-9a0d-d13c7683a7f2",

"Description1": "100 - Salary",

"WeightOrValue": "1",

"FKAccountID": "Salary_Exp",

"Flow": "None",

"IC": "None",

"UD1": "None",

"UD2": "None",

"UD3": "None",

"UD4": "None",

"UD5": "None",

"UD6": "None",

"UD7": "None",

"UD8": "None",

"Sequence": 10.0,

REST API Implementation Guide 22

REST API Overview

"FKClassID": "100_Salary"

},

]}}

Data ProviderGetAdoDataSetForCubeViewCommand
endpoint
1. Create new POST request in Postman,

2. Url= http(s)://[servername]:[port]/onestreamapi/api/DataProvider/
GetAdoDataSetForCubeViewCommand?api-version=5.2.0

3. Authorization: Type=Bearer Token. Token={{webapi_access_token}}

4. Headers: Content-Type=application/json

5. Body (raw / jSON):

{
"BaseWebServerUrl": [OneStream Server Logon URL],
"ApplicationName":[your application name],
"CubeViewName": [existing Cube View name],
"DataTablePerCubeViewRow ": [if true returns a Data Table Per Cube View row - bool],

"ResultDataTableName": [name of resulting table in the DataSet],

"CubeViewDataTableOptions": [set of formatting bolean options for the returned table -

Optional],

"CustomSubstVarsAsCommaSeparatedPairs": [comma separated list of key value pairs as

substitution variables with the
following format: "VariableName1=[VariableValue1],VariableName2=[VariableValue2],..."] -
Optional
}

Example:

REST API Implementation Guide 23

REST API Overview

"BaseWebServerUrl": "[Link]

"ApplicationName": "GolfStream_v37",

"CubeViewName": "Gross Margin",

"DataTablePerCubeViewRow": false,

"ResultDataTableName": "ResultDataTableNames",

"CustomSubstVarsAsCommaSeparatedPairs": "",

"CubeViewDataTableOptions": {

"IncludeTitle": false,

"IncludeHeaderLeftLabel1" : true,

"IncludeHeaderLeftLabel2" : true,

"IncludeHeaderLeftLabel3" : true,

"IncludeHeaderLeftLabel4" : true,

"IncludeHeaderCenterLabel1" : true,

"IncludeHeaderCenterLabel2" : true,

"IncludeHeaderCenterLabel3" : true,

"IncludeHeaderCenterLabel4" : true,

"IncludeHeaderRightLabel1" : true,

"IncludeHeaderRightLabel2" : true,

"IncludeHeaderRightLabel3" : true,

"IncludeHeaderRightLabel4" : true,

"IncludePovCube" : true,

"IncludePovEntity" : true,

"IncludePovParent" : true,

"IncludePovCons" : true,

"IncludePovScenario" : true,

"IncludePovTime" : true,

"IncludePovView" : true,

"IncludePovAccount" : true,

REST API Implementation Guide 24

REST API Overview

"IncludePovFlow" : true,

"IncludePovOrigin" : true,

"IncludePovIC" : true,

"IncludePovUD1" : true,

"IncludePovUD2" : true,

"IncludePovUD3" : false,

"IncludePovUD4" : true,

"IncludePovUD5" : false,

"IncludePovUD6" : true,

"IncludePovUD7" : false,

"IncludePovUD8" : true,

"IncludeMemberDetails": true,

"IncludeRowNavigationLink" : true,

"IncludeHasDataStatus" : true,

"IncludeAnnotation" : true,

"IncludeAssumptions" : true,

"IncludeAuditComment" : true,

"IncludeFootnote" : true,

"IncludeVarianceExplanation" : true

6. Click Send and observe the response at the bottom pane. If successful, a JSON data table
will be returned otherwise a descriptive error message will show. More details will be logged
in the Error and Activity logs.

This is a returned response from the request using the above body example in Postman:

"ResultDataTableNames": [

REST API Implementation Guide 25

REST API Overview

"RowId": 0,

"RowName": "Row1",

"HeaderLeftLabel1": "",

"HeaderLeftLabel2": "",

"HeaderLeftLabel3": "",

"HeaderLeftLabel4": "",

"HeaderCenterLabel1": "",

"HeaderCenterLabel2": "",

"HeaderCenterLabel3": "",

"HeaderCenterLabel4": "",

"HeaderRightLabel1": "",

"HeaderRightLabel2": "",

"HeaderRightLabel3": "",

"HeaderRightLabel4": "",

"PovCubeId": 5,

"Col8VarianceExplanation": ""

},

] } }

Data ProviderGetAdoDataSetForSqlCommand endpoint

1. Create new POST request in Postman,

2. Url= http(s)://[servername]:[port]/onestreamapi/api/DataProvider/
GetAdoDataSetForSqlCommand?api-version=5.2.0

3. Authorization: Type=Bearer Token. Token={{webapi_access_token}}

REST API Implementation Guide 26

REST API Overview

4. Headers: Content-Type=application/json

5. Body (raw / jSON):

{
"BaseWebServerUrl": [OneStream Server Logon URL],
"ApplicationName":[your application name],
"SqlQuery ": [sql query statement used to return data],
"DbLocation": [specify if data from an external database referenced in the configuration
will need to be returned - string - defaults to "Application" - Optional],

"ResultDataTableName": [name of resulting table in the DataSet],

"XFExternalDBConnectionNam ": [specify if DbLocation is set to "External”],

"CustomSubstVarsAsCommaSeparatedPairs": [comma separated list of key value

pairs as substitution variables with the following format: "VariableName1=
[VariableValue1],VariableName2=[VariableValue2],..."] - Optional
}

Example:

"BaseWebServerUrl": "[Link]

"ApplicationName": "GolfStream_v37",

"SQLQuery": "Select TOP 100 * from Cube",

"ResultDataTableName": "ResultDataTableName",

"DBLocation": "Application",

"XFExternalConnectionName": "",

"CustomSubstVarsAsCommaSeparatedPairs": ""

REST API Implementation Guide 27

REST API Overview

6. Click Send and observe the response at the bottom pane. If successful, a JSON data table
will be returned otherwise a descriptive error message will show. More details will be logged
in the Error and Activity logs.

This is a returned response from the request using the above body example in Postman:

"ResultDataTableName": [

"CubeId": 0,

"Name": "Houston",

"Description": "Houston Clubs",

"CubeType": 0,

"IsTopLevelCube": false,

"TimeDimProfileID": "664c9bd4-a314-4941-81be-513aeddac13a",

"AccessGroupUniqueID": "e31054d8-83bf-4f79-b563-0e450342de9e",

"MaintenanceGroupUniqueID": "e31054d8-83bf-4f79-b563-0e450342de9e",

"ConsAlgorithmType": 0,

"TransAlgorithmType": 0,

"CalcNoneConsIfNoData": false,

"CalcLocalCurrIfNoData": true,

"CalcTransCurrsIfNoData": false,

"CalcOwnerPreAdjIfNoData": false,

"CalcShareIfNoData": false,

"CalcElimIfNoData": false,

"CalcOwnerPostAdjIfNoData": false,

"BR1Name": "CorporateBusinessRules",

"BR2Name": "",

"BR3Name": "",

REST API Implementation Guide 28

REST API Overview

"BR4Name": "",

"BR5Name": "",

"BR6Name": "",

"BR7Name": "",

"BR8Name": "",

"DefaultCurrencyId": 176,

"FxRateTypeIDForRevExp": "89ce1f1c-c1cb-438e-9825-e00861a4fa5b",

"FxRuleTypeIdForRevExp": 1,

"FxRateTypeIDForAssetLiab": "89ce1f1c-c1cb-438e-9825-e00861a4fa5b",

"FxRuleTypeIdForAssetLiab": 0,

"XmlData": ""

},

...

] } }

IMPORTANT: The Administrator role is required for this functionality.

Data ProviderGetAdoDataSetForMethodCommand endpoint

1. Create new POST request in Postman,

2. Url= http(s)://[servername]:[port]/onestreamapi/api/DataProvider/
GetAdoDataSetForMethodCommand?api-version=5.2.0

3. Authorization: Type=Bearer Token. Token={{webapi_access_token}}

4. Headers: Content-Type=application/json

5. Body (raw / jSON):

{
"BaseWebServerUrl": [OneStream Server Logon URL],
"ApplicationName":[your application name],

REST API Implementation Guide 29

REST API Overview

"MethodQuery":[method query to return data],

"XFCommandMethodTypeId": [pre-defined list of XF method commands used by
XFDataProvider to fill a DataSet],
"ResultDataTableName": [name of resulting table in the DataSet],

"CustomSubstVarsAsCommaSeparatedPairs": [comma separated list of key value pairs as

substitution variables with the
following format: "VariableName1=[VariableValue1],VariableName2=[VariableValue2],..."] -
Optional
}

Example:

"BaseWebServerUrl": "[Link]

"ApplicationName": "GolfStream_v37",

"MethodQuery ": "{Houston}{Actual}{2018M1}{true}{}",

"XFCommandMethodTypeId ": "CertificationForWorkflowUnit",

"ResultDataTableName": "MyResultsTable",

"CustomSubstVarsAsCommaSeparatedPairs": ""

XFCommandMethodTypeId may take any values from the list below:

"WorkflowCalculationEntities"

"WorkflowConfirmationEntities"

"WorkflowProfileAndDependentProfileEntities"

"WorkflowProfileEntities"

"WorkflowProfiles"

"WorkflowProfileRelatives"

"WorkflowStatus"

"WorkflowStatusTwelvePeriod"

"WorkflowAndEntityStatus

"JournalsForWorkflowUnit"

REST API Implementation Guide 30

REST API Overview

"FormsStatusForWorkflowUnit"

"ConfirmationForWorkflowUnit"

"CertificationForWorkflowUnit"

"ICMatchingForWorkflowUnit"

"ICMatchingForWorkflowUnitMultiPlug"

"ICMatchingForWorkflowUnitMultiPeriod"

"ICMatchingPlugAccountsForWorkflowUnit"

6. Click Send and observe the response at the bottom pane. If successful, a JSON data table
will be returned otherwise a descriptive error message will show. More details will be logged
in the Error and Activity logs.

This is a returned response from the request using the above body example in Postman:

"MyResultsTable": [

"ProfileName": "Houston",

"ProfileKey": "2f3a719e-8e26-4d8c-8cc7-4544a4812673",

"ProfileOrder": 1,

"ScenarioName": "Actual",

"ScenarioKey": 0,

"TimeKey": 2018003000,

"TimeName": "2018M1",

"CertProfileKey": "003e0a15-6c9a-412c-90ba-64d31040c314",

"CertName": "Plant Certification",

"CertDescription": "Plant Certification",

"CertSignOffState": "Inprocess",

"CertIsCertified": false,

"CertCanCertify": false,

REST API Implementation Guide 31

REST API Overview

"CertIsParentCertified": false,

"CertAreDependantsCertified": false,

"CertAllAnswered": false,

"CertQuestionCount": 3,

"CertUnansweredCount": 3,

"CertUnansweredRate": 1.0,

"GroupKey": "7c7fedcd-f04a-4f5b-ba13-ed1097f449a9",

"GroupName": "SOX Plant Controller",

"GroupDescription": "SOX Plant Controller",

"GroupSignOffState": "Inprocess",

"GroupAllAnswered": false,

"GroupQuestionCount": 3,

"GroupUnansweredCount": 3,

"GroupUnansweredRate": 1.0,

"QuestionUniqueID": "8a92f59c-2419-49d2-87b7-1cdfb21c7072",

"QuestionName": "Unusual Transactions",

"QuestionCategory": "InternalAudit",

"QuestionRiskLevel": "High",

"QuestionFrequency": "AllTimePeriods",

"TimeFilterForReqtFreq": "",

"QuestionText": "Any unusual transactions booked? If so, explain. ",

"QuestionResponse": "-1",

"QuestionComments": "",

"QuestionResponseOptional": false,

"QuestionDeactivated": false,

"QuestionDeactivationDate": "1900-01-01T00:00:00",

"QuestionDisplayOrder": 10

},

REST API Implementation Guide 32

REST API Overview

"ProfileName": "Houston",

"ProfileKey": "2f3a719e-8e26-4d8c-8cc7-4544a4812673",

"ProfileOrder": 1,

"ScenarioName": "Actual",

"ScenarioKey": 0,

"TimeKey": 2018003000,

"TimeName": "2018M1",

"CertProfileKey": "003e0a15-6c9a-412c-90ba-64d31040c314",

"CertName": "Plant Certification",

"CertDescription": "Plant Certification",

"CertSignOffState": "Inprocess",

"CertIsCertified": false,

"CertCanCertify": false,

"CertIsParentCertified": false,

"CertAreDependantsCertified": false,

"CertAllAnswered": false,

"CertQuestionCount": 3,

"CertUnansweredCount": 3,

"CertUnansweredRate": 1.0,

"GroupKey": "7c7fedcd-f04a-4f5b-ba13-ed1097f449a9",

"GroupName": "SOX Plant Controller",

"GroupDescription": "SOX Plant Controller",

"GroupSignOffState": "Inprocess",

"GroupAllAnswered": false,

"GroupQuestionCount": 3,

"GroupUnansweredCount": 3,

"GroupUnansweredRate": 1.0,

REST API Implementation Guide 33

REST API Overview

"QuestionUniqueID": "78e102c2-cda5-4c07-b853-416d83de5706",

"QuestionName": "Audit Transactions",

"QuestionCategory": "ExternalAudit",

"QuestionRiskLevel": "High",

"QuestionFrequency": "AllTimePeriods",

"TimeFilterForReqtFreq": "",

"QuestionText":
"Any transactions to be reviewed by external audit? If so, explain. ",

"QuestionResponse": "-1",

"QuestionComments": "",

"QuestionResponseOptional": false,

"QuestionDeactivated": false,

"QuestionDeactivationDate": "1900-01-01T00:00:00",

"QuestionDisplayOrder": 20

},

"ProfileName": "Houston",

"ProfileKey": "2f3a719e-8e26-4d8c-8cc7-4544a4812673",

"ProfileOrder": 1,

"ScenarioName": "Actual",

"ScenarioKey": 0,

"TimeKey": 2018003000,

"TimeName": "2018M1",

"CertProfileKey": "003e0a15-6c9a-412c-90ba-64d31040c314",

"CertName": "Plant Certification",

"CertDescription": "Plant Certification",

"CertSignOffState": "Inprocess",

"CertIsCertified": false,

REST API Implementation Guide 34

REST API Overview

"CertCanCertify": false,

"CertIsParentCertified": false,

"CertAreDependantsCertified": false,

"CertAllAnswered": false,

"CertQuestionCount": 3,

"CertUnansweredCount": 3,

"CertUnansweredRate": 1.0,

"GroupKey": "7c7fedcd-f04a-4f5b-ba13-ed1097f449a9",

"GroupName": "SOX Plant Controller",

"GroupDescription": "SOX Plant Controller",

"GroupSignOffState": "Inprocess",

"GroupAllAnswered": false,

"GroupQuestionCount": 3,

"GroupUnansweredCount": 3,

"GroupUnansweredRate": 1.0,

"QuestionUniqueID": "3d9c4dcc-75fd-4568-b224-f7e428622917",

"QuestionName": "Key Data Review",

"QuestionCategory": "FinancialStatementReview",

"QuestionRiskLevel": "MediumLow",

"QuestionFrequency": "AllTimePeriods",

"TimeFilterForReqtFreq": "",

"QuestionText": "Have all key metrics been reviewed? ",

"QuestionResponse": "-1",

"QuestionComments": "",

"QuestionResponseOptional": false,

"QuestionDeactivated": false,

"QuestionDeactivationDate": "1900-01-01T00:00:00",

"QuestionDisplayOrder": 30

REST API Implementation Guide 35

REST API Overview

],

"MyResultsTable_SignOffCert": [

"ProfileKey": "2f3a719e-8e26-4d8c-8cc7-4544a4812673",

"ScenarioKey": 0,

"TimeKey": 2018003000,

"CertProfileKey": "003e0a15-6c9a-412c-90ba-64d31040c314",

"SignOffState": "Inprocess",

"Comments": "Sign-Off Initialized",

"UserKey": "2b61ed59-63ae-46f2-89aa-a8ee9f14bacd",

"UserName": "TestUserOkta",

"UserIPAddress": "8d3d857e-cd62-4fd9-a2ec-43b46217a036",

"TimeStamp": "2019-11-18T14:45:00.007"

],

"MyResultsTable_SignOffGroups": [

"ProfileKey": "2f3a719e-8e26-4d8c-8cc7-4544a4812673",

"ScenarioKey": 0,

"TimeKey": 2018003000,

"CertProfileKey": "003e0a15-6c9a-412c-90ba-64d31040c314",

"CertProfileName": "Plant Certification",

"GroupKey": "7c7fedcd-f04a-4f5b-ba13-ed1097f449a9",

"GroupName": "SOX Plant Controller",

"SignOffState": "Inprocess",

"Comments": "Sign-Off Initialized",

"UserKey": "2b61ed59-63ae-46f2-89aa-a8ee9f14bacd",

REST API Implementation Guide 36

REST API Overview

"UserName": "TestUserOkta",

"UserIPAddress": "8d3d857e-cd62-4fd9-a2ec-43b46217a036",

"TimeStamp": "2019-11-18T14:45:00.2"

IMPORTANT: The Administrator role is required for this functionality.

Authentication Execute LogonAndReturnCookie endpoint

Returns a message that indicates authentication state. Used mostly to verify the installation of
web API completed successfully.

1. Create new POST request in Postman,

2. Url= http(s)://[servername]:
[port]/OneStreamApi/api/Authentication/LogonAndReturnCookie?api-version=5.2.0

3. Authorization: Type=Bearer Token. Token={{webapi_access_token}}

4. Headers: Content-Type=application/json

5. Body (raw / jSON):

REST API Implementation Guide 37

REST API Overview

Arguments:
"BaseWebServerUrl": [OneStream Server Logon URL],
"ApplicationName" : [name of Application attempted to access]

<response code="200">Returns a JSON representation of the resulting

DataSet.</response>
<response code="400">Bad Request. Missing Authentication arguments. </response>
<response code="500">Error Message. Authentication Failed. Please check the Error Log
for more details</response>

Click Send and observe the response at the bottom pane. If successful, a message that
indicates authentication state will be returned. Otherwise the error message will be shown.
More details will be logged in the Error and Activity logs.

REST API Implementation Guide 38

REST API Overview

REST API Implementation Guide 39

Configure OneStream API for External Authentication

Configure OneStream API for

External Authentication
For customers in a self-hosted environment, we support REST API authentication with Azure
Active Directory (Azure AD [Microsoft Entra ID]), Okta, and PingFederate. Perform the
configuration for your provider:

l Azure AD (Microsoft Entra ID) Configuration

l Okta Configuration

l PingFederate Configuration

If you use the Modern Browser Experience, you must enter a REST API key in both the
OneStream Application Server Configuration and Web Server Configuration to enter OneStream
and browser clients. See the Installation and Configuration Guide.

For customers in a OneStream-hosted environment, see the Identity and Access Management
Guide for information about authentication with OneStream IdentityServer and using personal
access tokens (PATs).

Azure AD (Microsoft Entra ID) Configuration

To configure OneStream REST API to support Azure AD (Microsoft Entra ID) authentication,
follow these steps:

REST API Implementation Guide 40

Configure OneStream API for External Authentication

1. Configure the REST API Application Registration in Azure AD (Microsoft Entra ID).

2. Set Up the Web Server Configuration in OneStream.

3. Configure the User in OneStream.

To enable single sign-on with Azure AD (Microsoft Entra ID) for the OneStream Desktop
application, which includes the Windows Client application and the Excel Add-In, using OIDC
protocol, see the Installation and Configuration Guide.

Configure the REST API Application Registration in

Azure AD (Microsoft Entra ID)
To configure the REST API application registration, you need to copy the application (client)
ID from Azure AD (Microsoft Entra ID) and paste it into the Web Server Configuration in
OneStream.

1. Log in to your Azure AD account.

2. On the Home screen, click the App registrations icon.

3. On the App registrations page, click the + New registration tab.

4. On the Register an application page, complete the following fields:

a. Enter a name for the application.

b. For Supported account types, select Accounts in this organizational directory

only.

5. Click the Register button.

6. On the page for the application, in the Manage list on the left, select Authentication.

REST API Implementation Guide 41

Configure OneStream API for External Authentication

7. In the Advanced settings, under Allow public client flows, set the Enable the following
mobile and desktop flows option to Yes.

8. Click the Save button.

9. In the Manage list on the left, select Certificates & secrets.

10. In the Client secrets tab, click + New client secret.

11. In the Add a client secret dialog box, enter a description and select an expiration time in
the drop-down menu. Click the Add button.

12. On the Certificates & secrets page, copy the value for the client secret.

IMPORTANT: The client secret value may only be available to copy for a limited
time, so copy it immediately after it is created.

13. In the Manage list on the left, select Expose an API.

14. In Scopes defined by this API, click + Add a scope.

15. In the Add a scope dialog box, the application ID URI is automatically generated. Click the
Save and continue button.

NOTE: You can add a scope in this dialog box if needed.

16. On the Expose an API page, copy the application ID URI.

Set Up the Web Server Configuration in OneStream

1. Open the OneStream Server Configuration Utility application.

2. Go to File > New Web Server Configuration File.

NOTE: Alternatively, you can open an existing file to edit it.

REST API Implementation Guide 42

Configure OneStream API for External Authentication

3. In the Web Server Configuration Settings section, click the ellipsis to the right of Single
Sign On Identity Provider.

4. In the User Name Lookup field, type aud to include this claim in the ordered lookups.

NOTE: The claim aud indicates the intended audience for the token.

5. Click the ellipsis to the right of Azure Identity Provider.

REST API Implementation Guide 43

Configure OneStream API for External Authentication

6. In the Azure Identity Provider dialog box, in the REST API Settings section, complete the
following fields :

l OneStream Web Api Client ID: Enter the application (client) ID from Azure AD. See
Configure the REST API Application Registration in Azure AD (Microsoft Entra ID)
step 16.

TIP: To view the application (client) ID in Azure AD, go to the page for the
application and select Overview in the list on the left.

l OneStream Web Api App Custom Scopes: Enter custom scopes, or leave as
default (blank).

REST API Implementation Guide 44

Configure OneStream API for External Authentication

7. Click the OK button.

8. Save changes and reset IIS.

NOTE: Reset IIS after you save any changes to the Application Server
Configuration or Web Server Configuration.

Configure the User in OneStream

1. In the OneStream Desktop application, go to System > Security > Users > <user>.

2. In the Authentication properties, complete the following fields for REST API authentication
through Azure AD.

l External Authentication Provider: In the drop-down menu, select the Azure AD

configuration.

l External Provider User Name: Enter the application (client) ID from Azure AD. See
Configure the REST API Application Registration in Azure AD (Microsoft Entra ID)
step 16.

REST API Implementation Guide 45

Configure OneStream API for External Authentication

TIP: To view the application (client) ID in Azure AD, go to the page for the
application and select Overview in the list on the left.

3. Click the Save icon.

Azure AD (Microsoft Entra ID) Endpoints

We support v2.0 Azure AD endpoints.

1. On Manifest, find accessTokenAcceptedVersion.

2. Set the value to 2.

3. Click Save.

REST API Implementation Guide 46

Configure OneStream API for External Authentication

Set Up Postman Access Token Requests

1. Create a new POST request. Set url to [Link]
Id}/oauth2/v2.0/token with tenant ID value.

TIP: To view the directory (tenant) ID in Azure AD, go to the page for the
application and select Overview in the list on the left.

2. In the Authorization tab, select Basic Auth for type. In the Username and Password fields,
enter the client ID and client secret from the application registration, respectively. See
Configure the REST API Application Registration in Azure AD (Microsoft Entra ID) step 12.

TIP: To view the application (client) ID in Azure AD, go to the page for the
application and select Overview in the list on the left.

3. In the Headers tab, enter the following keys:

l Accept: application/json

l Authorization: Basic

l Content-Type: application/x-www-form-urlencoded

4. In Body, enter either option 1 or option 2:

a. Option 1:

i. grant_type: client_credentials

ii. scope: {AppId Uri}/.default for machine to machine use case

b. Option 2:

REST API Implementation Guide 47

Configure OneStream API for External Authentication

i. grant_type: password

ii. username: {Azure ad user name}

iii. password: {Azure ad user password}

iv. scope: {custom scope}

5. Click Send and notice the value of access_token in the response.

Okta Configuration
To configure OneStream REST API to support Okta authentication for M2M application
registration (grant_type = client_credentials), follow these steps:

1. Configure the REST API Application Registration in Okta.

2. (Optional) Add Authorization Servers and Scopes in Okta.

3. Set Up the Web Server Configuration in OneStream.

4. Configure the User in OneStream.

REST API Implementation Guide 48

Configure OneStream API for External Authentication

To enable single sign-on with Okta for the OneStream Desktop application, which includes the
Windows Client application and the Excel Add-In, using OIDC protocol, see the Installation and
Configuration Guide.

Configure the REST API Application Registration in

Okta
To configure the REST API application registration, you need to copy the client ID from Okta and
paste it into the Web Server Configuration in OneStream.

1. Log in to your Okta account.

2. In the Applications list on the left, select Applications.

3. Click Create App Integration.

4. In the Create a new app integration dialog box, for Sign-in method, select
API Services.

5. Click the Next button.

6. On the New API Services App Integration page, in the App integration name field,
enter the name of the Okta API application.

7. Click the Save button.

8. Copy the client ID. You will need to paste this into the Web Server Configuration in
OneStream.

Add Authorization Servers and Scopes in Okta

To configure authorization servers, copy the authorization server ID from the issuer URI and the
custom scopes from Okta and paste them into the Web Server Configuration in OneStream.

REST API Implementation Guide 49

Configure OneStream API for External Authentication

1. Log in to your Okta account.

2. In the Security list on the left, select API.

3. Click the Add Authorization Server button.

4. Enter a name and, in the Audience field, enter the client ID from the Okta application. See
Configure the REST API Application Registration in Okta step 8.

5. Click the Save button. The API page displays the list of authorization servers and the
corresponding issuer URIs. You will need to paste the authorization server ID from the
issuer URI into the Web Server Configuration in OneStream.

6. To add a custom scope to support the Machine-to-Machine scenario, on the API page,
select the authorization server.

7. Select the Scopes tab.

8. Click the Add Scope button.

9. Enter the information and click the Create button. You will need to paste these custom
scopes into the Web Server Configuration in OneStream.

Set Up the Web Server Configuration in OneStream

1. Open the OneStream Server Configuration Utility application.

2. Go to File > New Web Server Configuration File .

NOTE: Alternatively, you can open an existing file to edit it.

3. In the Web Server Configuration Settings section, click the ellipsis to the right of Single
Sign On Identity Provider.

REST API Implementation Guide 50

Configure OneStream API for External Authentication

4. Click the ellipsis to the right of Okta Identity Provider.

5. In the Okta Identity Provider dialog box, in the General and REST API Settings sections,
complete the following fields:

l Okta Authorization Server ID: Enter the authorization server ID from the issuer
URI in Okta. See Add Authorization Servers and Scopes in Okta step 5. Alternatively,
use the default value by either typing default or leaving as default (blank).

TIP: To view the list of authorization servers and the corresponding issuer
URIs in Okta, in the Security list on the left, select API.

REST API Implementation Guide 51

Configure OneStream API for External Authentication

l Okta Web Api Client ID: Enter the client ID from the Okta application. See Configure
the REST API Application Registration in Okta step 8.

l Okta Web Api Custom Scopes: Enter custom scopes, or leave as default (blank).
See Add Authorization Servers and Scopes in Okta step 9.

l Okta Web Api Authorization Server ID: Enter the server ID if using a custom
authentication server, or leave as default (blank).

6. Click the OK button.

7. Save changes and reset IIS.

NOTE: Reset IIS after you save any changes to the Application Server
Configuration or Web Server Configuration.

REST API Implementation Guide 52

Configure OneStream API for External Authentication

Configure the User in OneStream

1. In the OneStream Desktop application, go to System > Security > Users > <user>.

2. In the Authentication properties, complete the following fields for REST API authentication
through Okta.

l External Authentication Provider: In the drop-down menu, select the Okta

configuration.

l External Provider User Name: Enter the client ID from Okta. See Configure the
REST API Application Registration in Okta step 8.

3. Click the Save icon.

PingFederate Configuration
To configure OneStream REST API to support PingFederate authentication, follow these steps:

1. Configure the REST API Application Registration in PingFederate.

2. Set Up the Web Server Configuration in OneStream.

3. Configure the User in OneStream.

To enable single sign-on with PingFederate for the OneStream Desktop application, which
includes the Windows Client application and the Excel Add-In, using OIDC protocol, see the
Installation and Configuration Guide.

REST API Implementation Guide 53

Configure OneStream API for External Authentication

Configure the REST API Application Registration in

PingFederate
To configure the REST API application registration, you need to enter the same client ID in
PingFederate and the Web Server Configuration in OneStream. You also need to copy the client
secret from PingFederate, which is used to request a token.

1. Log in to your PingFederate account.

2. In the menu on the left, click OAuth Server.

3. Under the CLIENTS list, click the Create New button.

4. On the Client page, complete the following fields:

l CLIENT ID: Enter a client ID, which is a unique name or identifier for the application
registration.

l NAME: Enter the name of the client.

l CLIENT AUTHENTICATION: Select CLIENT SECRET.

l CLIENT SECRET: Select CHANGE SECRET and then click the Generate Secret
button.

l ALLOWED GRANT TYPES: Select Client Credentials.

5. Click the Save button.

Set Up the Web Server Configuration in OneStream

1. Open the OneStream Server Configuration Utility application.

2. Go to File > New Web Server Configuration File.

NOTE: Alternatively, you can open an existing file to edit it.

REST API Implementation Guide 54

Configure OneStream API for External Authentication

3. Click the ellipsis to the right of Single Sign On Identity Provider.

4. In the User Name Lookup field, type client_id to include this claim in the ordered lookups.

5. Click the ellipsis to the right of PingFederate Identity Provider.

REST API Implementation Guide 55

Configure OneStream API for External Authentication

6. In the PingFederate Identity Provider dialog box, in the REST API Settings section,
complete the following fields :

l OneStream Web Api Client ID: Enter the client ID you entered in PingFederate.
See Configure the REST API Application Registration in PingFederate step 4.

l OneStream Web Api Scopes: Enter custom scopes.

l OneStream Web Api JWKS Path: Enter the path on the PingFederate server to
publish a JSON Web Key Set with the keys and certificates used for signature
verification.

REST API Implementation Guide 56

Configure OneStream API for External Authentication

7. Click the OK button.

8. Save changes and reset IIS.

NOTE: Reset IIS after you save any changes to the Application Server
Configuration or Web Server Configuration.

Configure the User in OneStream

1. In the OneStream Desktop application, go to System > Security > Users > <user>.

2. In the Authentication properties, complete the following fields for REST API authentication
through PingFederate.

l External Authentication Provider: In the drop-down menu, select the

PingFederate configuration.

l External Provider User Name: Enter the client ID you entered in PingFederate.
See Configure the REST API Application Registration in PingFederate step 4.

3. Click the Save icon.

REST API Implementation Guide 57

Configure OneStream API for External Authentication

Configure the AUD Value

In some installations, the Audience value is not used in the authentication process. Normal
processing will cause authentication to fail if this value is not used. The Validate Audience option
allows for disabling audience validation for these installations.

By default, this setting is True, which means the audience will be validated.

1. Open the OneStream Server Configuration Utility application.

2. Go to File > Open Web Server Configuration File.

3. Find the Web Server Configuration file and click the Open button.

4. Click the ellipsis to the right of Single Sign On Identity Provider.

5. In Validate Audience, select False to disable Audience validation.

REST API Implementation Guide 58