Register Developer Account and Create Your Test Tenant

To start developing your app for SAP Anywhere, you have to join SAP Anywhere Developer Program to obtain a developer account. So far the developer registration is not opened to all users. You can contact us and then we will send you an invitation email. You can follow the instructions in this invitation email to register your developer account.

As a developer, you are able to access the SAP Anywhere Developer Center dashboard and create your own testing tenant. The testing tenant is an area for app development where you can create data to test out the functionality of your app.

To create your own testing tenant, navigate to the Testing Sandbox tab and click Create button.

sandbox

Once the testing tenant is created, the next step is to create your app.

Create Your Public App

To create your app, you need to log in to your SAP Anywhere Developer Center, select the My Apps tab and click on Create App button.

The apps you create in your SAP Anywhere Developer Center function as public apps. You can also develop private apps. Private apps have the same functionality as public apps except that they can be applied to only one tenant. To learn how to use the API to create and generate a private app, please visit Build Private App.

Once you click Create App button, you will need to fill out the form displayed below. This form sets up the basic information to create your app and generate your API access credentials.

  • App Name The app name should be unique in App Center scope and cannot be a duplicate of other developers' app names.

  • App Icon The app icon will be shown in the App Center.

  • Install this app from The location from which you expect your users to install your app from. Two options are:

    • SAP Anywhere App Center Users will find your app in SAP Anywhere App Center and install the app from there by clicking the Install button;

    • Third Party App Store Users will find your app in SAP Anywhere App Center, but there will be an Open button instead of the Install button. They will be navigated to a third party app store (e.g. Zapier, Apple App Store, etc.), from which they can download or install the app. For this particular option type, your will be asked to provide your app URL in the third-party app store before publishing to SAP Anywhere App Center.

  • Application URL After the app is installed to SAP Anywhere, there will be a tile in Apps > Public Apps. When users click the tile, they will be redirected to this URL.

  • Installation URL When users click the Install button of the app in App Center, they will be redirected to this URL.

app info

App Detail Information

Once the app is created, you will get the following detailed information about the app:

app key
  • API Key and Secret

API key and secret are the credentials to access SAP Anywhere APIs. SAP Anywhere APIs are built on top of OAuth 2.0 protocol, and the API key and secret are synonymous to the OAuth 2.0 client ID and secret. For detailed information about them please refer to the sections below.

  • Authorization Service Endpoint

The authorization endpoint will be used in your app for authorizing.

  • SAP Anywhere API Endpoint

The API endpoint is used in your app to get SAP Anywhere data. For detailed information, please refer to Access Open API.

App Advanced Settings

Once your app is created, you can click the Advanced Settings tab in the app details page to create custom fields for app.

advanced setting

After clicking the Add button, you will need to fill out the form displayed below. It will let you create custom fields for your app. You can create a maximum of 10 custom fields for one app.

app udf
  • API Name The API name should be unique to one App.

  • Business Object The name of the Business Object for which custom fields will be created.

  • Type The type of the custom field.

Install App Into Your Test Tenant

Once your app is created, select the App Center Information tab in the app details page and clicking the Preview button to open the Unpublished App page.

app store listing

After you enter the Unpublished App page, you can press the Install button to install your app to the test tenant.

Process Install Request

When users click the Install button in the App Center, they will be redirected to your client server’s Installation URL. Three parameters will be sent to your Installation URL endpoint with a GET request, e.g.:

https://example.com/oauth/install?op=install&timestamp={timestamp}&hmac={hmac}
  • op The op parameter is always "install" in this case.

  • timestamp A value appended by the SAP Anywhere server. It is used to calculate the hmac value.

  • hmac hmac is used by the client server to ensure that the request is coming from SAP Anywhere. It is calculated with the timestamp parameter, your api key and api secret through using 'sha256'. For detailed information, please refer to the Verification Request section.

Ask for Permission

When you receive the install request above, you can ask users for permission to access SAP Anywhere APIs. This is done by displaying a prompt provided by SAP Anywhere.

oauth app install

To show the prompt, redirect the user to this URL:

{authorization_endpoint}/oauth2/authorize?response_type=code&client_id={api_key}&scope={scopes}&redirect_uri={redirect_uri}

With below substitutions made:

  • {authorization_endpoint} - Substitute with Authorization Service Endpoint shown in your app, see App Detail Information.

  • {api_key} - Substitute this with the app’s API key.

  • {scope} - Substitute with BusinessData_RW. For more information, please go to Scopes.

  • {redirect_uri} - The location to redirect after users authorize the client. This URL must be identical to the Application URL or Installation URL.

Confirm Installation

When users click the Install button in the prompt above, they will be redirected to your client server as specified above. One of the parameters passed in the confirmation redirect is the authorization code (the other parameters will be covered later in the guide).

https://example.com/some/redirect/uri?code={authorization_code}&timestamp={timestamp}&hmac={hmac}

For details of hmac verification information, please refer to the Verification Request section.

The authorization code can be used to exchange for an access token. The exchange is made with a POST request to the authorization server.

POST {authorization_endpoint}/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id={api_key}&client_secret={api_secrect}&grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_uri}

With below substitutions made:

  • {authorization_endpoint} - Substitute with Authorization Service Endpoint shown in your app, see App Detail Information.

  • {api_key} - Substitute with the app’s API key.

  • {api_secret} - Substitute with the app’s API secret.

  • {authorization_code} - Substitute with the authorization code provided in the redirect described above.

  • {redirect_uri} - The redirect_uri must be equal to the URI you passed in the Ask for Permission step.

The server will respond with an access token.

{
  "access_token":"9cf227d0-442a-49ab-a901-d1ff3c7acdf1",
  "token_type":"bearer",
  "refresh_token":"af8a9320-f353-461c-b552-43bc50fdf0f2",
  "expires_in":43199,
  "scope":"BusinessData_R BusinessData_RW"
}
  • access_token Used to access the tenant’s data through SAP Anywhere API. For more details about Open API, please refer to API Specification and API Reference sections. access_token will expire in 12 hours.

  • refresh_token Used to retrieve a new access_token after it’s expired. Apps should store the token somewhere to make authenticated requests for a tenant’s data. refresh_token will expire in 3 years.

To retrieve a new access_token with a refresh_token, please send the POST request below:

POST {authorization_endpoint}/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id={api_key}&client_secret={api_secret}&grant_type=refresh_token&refresh_token={refresh_token}
  • {authorization_endpoint} - Substitute with Authorization Service Endpoint shown in your app, see App Detail Information.

Once you get the access_token, you can access SAP Anywhere API; please refer to Access Open API.

Obtain User Information

There will be a tile in Apps > Public Apps page, after your app is installed to SAP Anywhere. When users click the tile, they will be redirected to the Application URL of your app.

To obtain current user’s information, either supporting login with SAP Anywhere account or binding with the existing account in your app, you can:

  1. Follow steps similar to those in the Ask for Permission and Confirm Installation sections, obtaining an authorization code and exchanging it for an access Token. Please choose a proper authorization scope according to section Authorization Scopes;

  2. Refer to Access Open API to send an API request as below. The user code contained in the response is the identity of the current user.

GET https://api.sapanywhere.com/v1/Users/me HTTP/1.1
Accept: application/json
Access-Token: a5b261ed-a25f-4be9-a099-c0bfe4db1050

Test Your App

After the app is installed in the testing tenant, you can access it as follows:

  1. Open the testing tenant by clicking the testing sandbox link in Developer Center’s Testing Sandbox page;

  2. Go to testing tenant’s Apps > Public Apps page;

  3. Click the icon of your app.

You will be navigated to your Application URL, as filled in the Create Your Public App section.

NOTES: For apps to be installed from Third Party App Store, you should access your app by following this app store’s guide.

Uninstall App

When users uninstall your app, we will send an uninstall message to your app so you can perform a clean up. The payload below will be sent to your Installation URL endpoint with a POST request:

{
    "payload": {
        "event_type": "APP_UNINSTALL",
        "tenant_code": 8849897553949,
        "user_code": 8847632629760
    },
    "hmac": "e1c9b653a136f91252699f46ca4bd4e48bca6c76a262d36b5f9807f22dc75568",
    "timestamp": "1462946140900"
}
  • timestamp A value appended by the SAP Anywhere server, used to calculate the hmac value.

  • hmac Used by the client server to ensure that the request is coming from SAP Anywhere. It is calculated with the timestamp parameter, your api key, and api secret by using sha256. For detailed information, please refer to the Verification Request section.

Authorization Scopes

At present, two scopes (BusinessData_RW and account) are supported when you make the authorization request, see Ask for Permission. More scopes will be introduced in the near future.

  • BusinessData_RW - This scope allows you to access all SAP Anywhere Open APIs. This might be the scope used to install your app if your app has full capability to access SAP Anywhere.

  • account - This scope allows you only to access only the User API. This might be the case when you use SAP Anywhere as the Identity Provider (IdP) for your application.

Verify SAP Anywhere Request

Every request from SAP Anywhere to the client server includes a hmac parameter that can be used to ensure that the request came from SAP Anywhere.

To verify that a request is valid, first get timestamp parameters from within the request. Then concatenate this timestamp with your API key into a single string as below:

"apiKey=4981285081829764-CfXsTlEbxPjBOcQbuBPCpM4CLNyvKVRI&timestamp=1444716850834"

Lastly, this string processes through a HMAC-SHA256 using the API Secret as the key. The message is authentic if the generated hexdigest is equal to the value of the hmac parameter.

digest = OpenSSL::Digest.new('sha256')
secret = "{API secret}"
message = "apiKey=4981285081829764-CfXsTlEbxPjBOcQbuBPCpM4CLNyvKVRI&timestamp=1444716850834"

digest = OpenSSL::HMAC.hexdigest(digest, secret, message)
digest == "54134b6f29182ed80f9e3a43a2b3e68efdd1413684c9584207fb6e2b497207a2"