Skip to Content
Author's profile photo Patrick Voelker

SAP Analytics Cloud APIs: Getting Started Guide

Application Programming Interfaces (APIs) allow developers to access predefined services and at the same time hide these services’ implementation complexity. In recent years, APIs have gained popularity as more and more companies have decided to expose their data and functionalities. On the one hand, making data/ functionality accessible to partners and customers is a key driver for the development of innovative solutions. On the other hand, it allows one application to access another applications’ services which is indispensable for connecting enterprise applications.

Last year, SAP Analytics Cloud (SAC) has started opening up access to its data by publishing the REST API. Last month, the URL API followed. Both, URL and REST API, have been published on API Hub. The REST API conforms to the OpenAPI specification.

This blog post is intended as a user guide for the URL API and the REST API of SAC. Before diving into the APIs themselves, we deal with how OAuth 2.0 can be implemented to let third-party applications access our protected resources on SAC. Once, a third-party application is authorized, it can make an API call to SAC.

This blog post is structured as follows:

1. User Authorization through OAuth 2.0 in SAC

1.1. Client Registration

1.2. Authorization Code Grant (three-legged)

1.2.1. Registration Details

1.2.2. Obtaining the Access Token

1.3. Client Credentials Grant (two-legged)

1.3.1. Registration Details

1.3.2. SAML Bearer Assertion


2.1. Enable iFrame Embedding

2.2. Compose the URL

2.2.1. Display Parameters

2.2.2. Filter Parameters

2.2.3. Variable Parameters




1. User Authorization through OAuth 2.0 in SAC

SAC allows third-party applications to access its web services by using the authorization protocol OAuth 2.0. With OAuth 2.0, we are able to make web service calls without exchanging user credentials between applications (cf. the standard RFC 6746).

The four entities which are involved in the OAuth protocol are:

  • Resource Owner: Grants access to a protected resource (can be the end-user).
  • Resource Server: Provides the protected resource to the client.
  • Client: Requests the protected resource. (Please note that this entity is independent from its implementation i.e., the ‘client’ can also be a server.)
  • Authorization Server: Authorizes the client and grants access tokens.

Translated to our context, the resource owner is the end-user, the resource server (Service Provider) is SAC, the client is any third-party application (client- or server-side application) and the authorization server is our Identity Provider (IdP) (per default the SAP Cloud Platform Identity Authentication Service).

The authorization server issues two types of tokens: access tokens and refresh tokens. While access tokens grant a user access to a protected resource, refresh tokens are mainly used to acquire a new access token when the current access token becomes invalid (e.g., because it has expired).

Below, we will at first register a third-party application as OAuth-client. Thereafter, we will see how to retrieve data from SAC implementing either the original three-legged or the two-legged OAuth flow.


1.1. Client Registration

Having administrator privileges on our SAC tenant, we can register an OAuth-client in the App Integration tab of the administration page. We navigate to the administration page by clicking on (Main Menu) -> System -> Administration.

Within the App Integration tab (1), we are now able to register a new OAuth client by clicking on +Add New OAuth Client (2).


This is opening the dialogue box for registering a new OAuth Client. Having chosen a name (1) and ID (2) for our client, we specify the authorization method which we want to use for obtaining tokens from the authorization server (3).

Currently, two authorization methods are available: Authorization Code Grant and Client Credentials Grant. In short, Authorization Code Grant is used for client-side applications consuming an API and Client Credentials Grant is used for authorizing server-side applications.


1.2. Authorization Code Grant (three-legged)

Authorization Code Grant is used when applications make API requests on behalf of the end-user. Hence, this authorization type requires interaction with the resource owner, or rather end-user interaction. The end-user gives her e.g., mobile or web application access to a protected resource on the Service Provider without the Service Provider getting to know her user credentials (cf. RFC 6749).

To implement the Authorization Code Grant flow, the client needs to be registered as OAuth client (1.2.1. Registration Details) and get an access token from the authorization server (1.2.2. Obtaining the Access Token).


1.2.1. Registration Details

At first, we finish registering the application as OAuth Client. We select Authorization Code under Authorization Grant and optionally define a lifetime for the authorization code (1).

Specifying a secret is an additional security measure and optional (2). If set, our client can only obtain an authorization code from the authorization server when knowing the secret.

Under Redirect URI we indicate the callback URL the authorization server returns the client to after successful authorization (3).

The client is able to parse the authorization code from the callback URL’s query string (e.g. http://localhost:8080/callback?code=1234abcd-5678-e9fg-h123i-4567jkl8mnop).

Defining a lifetime for access and refresh tokens is again optional (4).

For further information on the configuration, please kindly refer to Configuring OAuth 2.0 Authorization Code Grant Workflow and Managing OAuth Clients.


1.2.2. Obtaining the Access Token

The diagram below depicts the Authorization Code Grant flow tailored to our context and guides you towards its implementation. As previously mentioned, the end-user authorizes an application to access a protected resource on the the Service Provider (SP). Therefore, the end-user has to interact with the IdP (authorization server).

Please note that the SCP Authentication Service is the default IdP which can be changed.

Our custom application should first send the user to the URL of the authorization server’s authorization endpoint (Authorization URL). After obtaining the authorization code, the application has to exchange it for an access token. This is done by making a POST request with the authorization code to the authorization server’s token endpoint (Token URL).

Authorization URL (4) and Token URL (5) can be found within the App Integration tab (2) under OAuth Clients (3) on SAC’s administration page (1).


1.3. Client Credentials Grant (two-legged)

As opposed to the authorization type Authorization Code Grant, Client Credentials Grant is used for “machine-to-machine” authorization. Typically this flow is used when the protected resource does not belong to a specific user. Instead, the program is the resource owner. Hence, Client Credentials Grant does not require any interaction with the end-user. In fact, the client makes API requests on behalf of itself and handles the authorization process (cf. RFC 6749).

To implement the Client Credentials Grant flow, the client needs to be registered as OAuth client (1.3.1. Registration Details) and provide a Security Assertion Markup Language Bearer Assertion (1.3.2. SAML Bearer Assertion).


1.3.1. Registration Details

Just like in the case of client-side applications, we have to register our server-side application as OAuth Client. We select Client Credentials under Authorization Grant (1) and specify a secret (2). Optionally, we can define the lifetime for access tokens (3).

For further information on the configuration, please kindly refer to Configuring OAuth 2.0 SAML Bearer Assertion Workflow and Managing OAuth Clients.


1.3.2. SAML Bearer Assertion

Contrary to Authorization Code Grant, Client Credentials Grant requires a SAML assertion for authorization. This assertion has to be signed by the IdP we would like to use and must furthermore be known to SAC. Therefore, we have to save the assertion’s certificate as a Trusted IdP on SAC’s administration page (1) within the App Integration (2) tab under Trusted Identity Providers (3) (cf. Managing OAuth Clients and Trusted Identity Providers).

In case the server-side application is deployed on SAP Cloud Platform (SAPCP), the burden of implementing the OAuth protocol is not entirely placed on the shoulders of the developer. Instead, we can make use of the support which is provided by SAPCP i.e., SAML Bearer Assertion Authentication.




The URL API enables you to embed SAC stories in third-party applications. These stories are embedded in our website with inline frames (iframes).


2.1. Enable iFrame Embedding

By default embedding SAC stories in iframes is not allowed. Thus, we have to change our tenant’s settings to enable iframe embedding. This can be done on the tenant’s administration page ( -> System -> Administration).

Within the administration page, we choose the App Integration (1) tab. In the section Trusted Origins (2) we can specify the origins (3) for which we want to allow iframe embedding:

Furthermore, we have to allow cookies from in Google Chrome. This can be done in Chrome’s settings (1) under Advanced (2) -> Privacy and security (3) -> Content settings (4) -> Cookies.


2.2. Compose the URL

Now that we have enabled iframe embedding on our tenant, we compose the URL of the story to be embedded in the iframe. A story is referenced like this:

  • https://<TENANT>/sap/fpa/ui/tenants/<TENANT_ID>/bo/story/<STORY_ID>

<TENANT> is a placeholder for our tenant’s public URL. The <TENANT_ID> refers to the ID that has been assigned to our tenant. The <STORY_ID> indicates which story we want to open. The values to replace these placeholders can be found in the URL that opens when selecting a story in SAC (-> Browse -> Stories -> e.g., MyFavouriteStory):


The URL for opening our story may look like this:


Now we can append a query component (also known as query string) to the URL of our story. The query component can contain different parameters, each of which is specified as key-value pair. We can add parameters to define how a story is displayed in the iframe, parameters to filter a dimension with a certain value and parameters to initialize story variables.

As usual, the query component is preceded by a ‘?‘. It can contain multiple key-value pairs. Key and value are separated by ‘=‘. Different key-value pairs are separated by ‘&‘.

In the following, we briefly introduce the parameters that can be added to an URL. A detailed description can be found in the official documentation.


2.2.1. Display Parameters

Display parameters indicate how a story is displayed. They can be combined with Filter and Variable Parameters. We are able to indicate the mode we want to open the story in (key: mode), en-/ disable the page bar (key: pageBarand specify the page we want to open (key: page). A URL could look like this:



2.2.2. Filter Parameters

With filter parameters we can apply story filters. We can specify the model we want to use the filter on (key: f<XX>Model), the dimension we want to apply the filter to (key: f<XX>Dim), the values we want to filter for (key: f<XX>Val) and the filtering operator (key: f<XX>Op).

<XX> within a key is a freely selected two-digit number and is used to specify which parameters belong together. This is particularly important when more than one filter is passed (cf. URL below). Please keep in mind that the parameters that are passed within an URL have to be encoded (cf. URL-/ Percent-Encoding). A URL could look like this:


The values for the keys f<XX>Model, f<XX>Dim and f<XX>Val are internal IDs. The ID of a model can be found by opening a model in SAC’s modeler (-> Browse -> Models) (in the screenshot below: t.X.ApiDemoModel:ApiDemoModel).

We find the ID of a dimension by opening the filter bar within our story. The filter bar opens by clicking on the Story Filter icon in the Tools section (1) . To see the ID of a dimension, we click on the filter icon (2) and on Dimensions. Hovering over a dimension (in the screenshot below: Employee) brings up a tooltip which contains the dimension ID. The dimension ID is the string preceding the name in brackets (in the screenshot below: Sapphire_SF_TEST).

The ID of a filter value can be found by opening the filter dialogue. The filter dialogue shows all available dimensions of a model (cf. (3) in the previous screenshot). In the filter dialogue, we click on the dimension that we want to apply the filter to (in our example: Employee). This will bring up the Set filters dialogue. Within the Set filters dialogue, we see the ID of each possible filter value by hovering over the value (in the screenshot below: E223640).


2.2.3. Variable Parameters

As you know, we can use variables in SAC to create calculated values. These variables can be initialized by setting variable parameters in the query component of our URL. Having specified the model (key: v<XX>Model) and variable (key: v<XX>Par), we set the value we want to initialize our variable with (key: v<XX>Val).

<XX> within a key is a freely selected two-digit number and is used to specify which parameters belong together. This is particularly important when more than one filter is passed (cf. URL below). Please keep in mind that the parameters that are passed within an URL have to be encoded (cf. URL-/ Percent-Encoding). A URL could look like this:


The values for the keys v<XX>Model and v<XX>Par are internal IDs. The ID of a model can be found by opening a model in SAC’s modeler ( -> Browse -> Models) (in the screenshot below: t.X.ApiDemoModel:ApiDemoModel).

 We can list the IDs of all variables within a story by opening a story in SAC and selecting { } (Edit Prompts) in the toolbar. From there, we can choose the variable we want to initialize (in the screenshot below: Variable00 or Variable01).




Using SAC REST API endpoints, any requesting authorized application can access data stored on the tenant. (official documentation)

Below you can find an overview over the endpoints that are currently accessible to third-party applications.

HTTP Request Endpoint Description HTTP Response
GET api/v1/stories Returns all stories on the tenant with meta-information. 200 (OK), 403 (Not authorized), 500 (Internal server error)
POST api/v1/stories?copyFrom=<srcStoryId> Copies the story that is referenced by <srcStoryId>. Optionally, you can define the destination folder by appending &copyTo=<folderName>. 201 (Created), 400 (Bad request), 403 (Not authorized), 404 (Not found), 500 (Internal server error)
PATCH api/v1/stories/<storyId> Renames the story that is referenced by <storyId>. 200 (OK), 400 (Bad request), 403 (Not authorized), 404 (Not found), 500 (Internal server error)
DELETE api/v1/stories/<storyId> Deletes the story that is referenced by <storyId>. 200 (OK), 403 (Not authorized), 404 (Not found), 500 (Internal server error)


To access an endpoint, we simply append it to the tenant’s base URL (cf. screenshot below).

A sample GET request could look like this:

Making a GET request, it is possible to specify which meta-information shall be included in the response e.g., models. We simply set the includeparameter by appending the following query string to our endpoint: ?include=models

To show you what a response looks like, we consider the following GET request

which returns a JSON Array of story objects including all models that are used in a story. For illustration purposes, you see a JSON Array containing one story object (including model objects) in the following:

	"id": "8114AB5AE4CA9906E10000000A4E7468",
	"name": "JF Tech 3.0 -  API Demo",
	"description": "",
	"created": "2018-03-16T14:43:18.081Z",
	"createdBy": "MyFavouriteUser",
	"changed": "2018-04-13T06:54:28.412Z",
	"changedBy": "MyFavouriteUser",
	"models": [{
		"id": "t.16.SAP_SuccessFactors:SAP_SuccessFactors",
		"description": "Sapphire"
		"id": "t.16.SAP_Concur:SAP_Concur",
		"description": "Sapphire Concur"
		"id": "t.16.SAP_Cloud4Customer:SAP_Cloud4Customer",
		"description": "Sapphire C4C"
		"id": "t.16.SAP_Fieldglass:SAP_Fieldglass",
		"description": "Sapphire_Fieldglass"
		"id": "t.16.Sapphire_S4_V2:Sapphire_S4_V2",
		"description": "Sapphire_S4_V2"
		"id": "t.X.ApiDemoModel:ApiDemoModel",
		"description": "ApiDemoModel"
	"openURL": "/sap/fpa/ui/tenants/000/bo/story/8114AB5AE4CA9906E10000000A4E7468",
	"isTemplate": false,
	"isSample": false


Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo David Richert
      David Richert

      Hi, the value for the filter parameter isn't "Op", it's "Val". So in the text it is wrong, but it is correct in the URL example. Thanks!

      Author's profile photo Patrick Voelker
      Patrick Voelker
      Blog Post Author

      Hi David,
      Many thanks for pointing this out. It has been corrected.

      Author's profile photo Effie Zheng
      Effie Zheng

      very good blog! thanks!

      Author's profile photo Caio Silva
      Caio Silva
      I was able to execute the gettoken method successfully, 
      but when I try to view the story, it is returning the error: 
      Access to XMLHttpRequest at '' from origin '' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: Redirect is not allowed for a preflight request.
      Did you get this error? can anybody help me?
      Caio Silva
      Author's profile photo Haihua zhang
      Haihua zhang

      very good blogs! thanks!

      And I have a question ,  i use live connect with sap bw/4 on-premise system with saml2 sso authentication.
      However this cause that sap analytics cloud has the saml2 assertion from sap cloud platform , and it can’t establish the sso connection with BW/4. Is there a solution for this ?

      Author's profile photo Nagavenkata Mittapalli
      Nagavenkata Mittapalli

      Nice blog, can we have similar kind of approach for embedding Designer App into third party apps also ?
      The SAP's official documentation on the same is not that informative to consume.

      Author's profile photo Devender Reddy
      Devender Reddy

      Hi Patrick,

      Looking for REST API within our SAC for User Activity details for external Security Information and Event Management (SIEM) tool managed by my client.

      SCP itself has SIEM in the back-end, but client wants to connect their tenant and manage User Activity integrated with their other software/tools.

      I browsed through API hub and did not find any details on User Activity API.

      Essentially I am looking for

      <tenant_url>/sap/fpa/ui/app.html#;view_id=security-audit-report info from REST API.



      Author's profile photo Dmitry Kuznetsov
      Dmitry Kuznetsov

      Very nice one, indeed. The last bit is what was interesting to me to get the story metadata in some format.


      What I am also looking for is to get Application metadata (those App Design files, not regular SAC stories). This seems not to be available. Would you consider trying to explore such a possibility? It probably is just a copy-paste of code 🙂

      Author's profile photo Alessandro Biagi
      Alessandro Biagi

      Hi Patrick.

      I have a question related to SAC OAuth 2.0 support.

      I have a couple of stories and DiBos in my SAC demo tenant (on NEO) that I share with customers and prospects through and application, registered in SAC as a client app, which embeds them in an iframe.

      To avoid giving away user credentials for content viewers I use an OAuth 2.0 workflow based on authorization code to get a bearer token.

      In SAC on NEO I can set the token expiration to, for example, one year, so I do a new authorization flow each year and that works fine.

      The problem is that all tenants are being migrated to CF and there it's not possible to set the token expiration (it's fixed in 1 hour) and the refresh token (which lasts 720 hours) must be used to renew the token each hour. This will break my current scenario.

      As I have a "tech user" with strict view permissions that I use in the authorization flow to get the token, isn't there any way to do such authorization without user interaction using those credentials (i.e. setting grant_type=password)?

      I really want to avoid exposing the user credentials to the public (NOTE: my tenants are using the default SAC IdP).


      Author's profile photo TARUN PATODI

      Thank you for such a nice blog!!!

      Is there a way to find model id used in Analytical Application through API?

      Author's profile photo Pavan Golesar
      Pavan Golesar

      Very nice blog! even now its helpful!

      Author's profile photo Dharmateja Nandipati
      Dharmateja Nandipati

      Patrick Voelker  Is it possible to access SAC models created using live connection?The below link is not showing me SAC live models.

      https://<SAC Tenant URL>/api/v1/dataexport/administration/Namespaces(NamespaceID='sac')/Providers

      Author's profile photo Aleksandr Maksimtsev
      Aleksandr Maksimtsev

      Hi, Dharmateja Nandipati.

      I have the same problem. Were you able to extract the data from SAC Live model ?