API Reference | PUBLIC
SAP Fieldglass
2024-07-11
REST API Integration
General Reference Guide
© 2024 SAP SE or an SAP aliate company. All rights reserved.
THE BEST RUN
Content
1 Introduction .................................................................. 3
2 How the REST API Resource Works................................................. 4
3 Conguring Authentication and Authorization.........................................6
3.1 OAuth2 Service Authentication......................................................6
Congure X.509 Certicate Authentication...........................................7
3.2 Obtaining an Access Token from SAP Fieldglass Server.....................................11
3.3 Token Expiration................................................................12
4 HTTP Response Codes..........................................................14
2
PUBLIC
REST API Integration
Content
1 Introduction
Provides general reference information on the SAP Fieldglass REST API resource.
The SAP Fieldglass REST API resource allows clients to send and receive integrated data directly against the
application. Information can either upload (POST or PUT) or download (GET) data from the authenticated user,
with data In/Out supported in JSON/CSV formats. SAP Fieldglass can also PUSH data real time to the client-
dened end point, where applicable.
This guide provides the following information:
• how the API works
• how to use OAuth 2.0 protocol to access the API
• how to obtain and congure authentication and authorization
• associated HTTP response codes
When conguring an SAP Fieldglass API integration, rst refer to this guide for general information. Then refer to
the detailed technical specications related to the integration you're coding, as noted in the applicable Resource
URL topic in the next section.
REST API Integration
Introduction
PUBLIC 3
2 How the REST API Resource Works
An overview of the SAP Fieldglass REST API, using OAuth 2.0 protocol for authorization and URL resources for
coding specications.
Workow
The SAP Fieldglass REST API resource allows clients to send and receive integrated data directly against
the application. The API uses the OAuth 2.0 protocol for authorization. OAuth 2.0 uses tokens over HTTPS.
SAP Fieldglass supports common OAuth 2.0 scenarios such as those for web server, installed, and client-side
applications.
To begin, you must obtain OAuth 2.0 client credentials from your SAP Fieldglass representative. Next, your client
application requests an access token from the SAP Fieldglass Authorization Server, extracts a token from the
response, and then sends the token to the SAP Fieldglass REST API that you want to access.
All applications follow a basic pattern when accessing an SAP Fieldglass REST API using OAuth 2.0.
The following diagram illustrates the API authentication and authorization workow.
4
PUBLIC
REST API Integration
How the REST API Resource Works
Connector Resource URL
https://<SAP Fieldglass environment URL>/api/vc/connector/<connector name>
• Download connectors submit an HTTP GET request.
• Upload connectors submit an HTTP POST or PUT request.
To access the SAP Fieldglass Connector Library on the SAP Help Portal, go to https://help.sap.com/viewer/
9cfd5c12ee3046d59453e73974f9c4b7/Latest/en-US.
Approvals Resource URL
https://<SAP Fieldglass environment URL>/api/v1/approvals
Real-time push requests are sent to the end point identied by the customer. To fulll the request, SAP Fieldglass
needs to receive the following details:
• End Point URL
• Username and Password credentials
To access additional SAP Fieldglass API resources on the SAP API Business Hub, go to https://api.sap.com/
package/FieldglassAPI?section=Artifacts .
For more information on implementing REST APIs contact the Customer Support Help Center for SAP Fieldglass.
REST API Integration
How the REST API Resource Works
PUBLIC 5
3 Conguring Authentication and
Authorization
The following steps summarize how to obtain OAuth 2.0 authorization and access token from SAP Fieldglass.
1. Obtain OAuth 2.0 client credentials from your SAP Fieldglass Representative.
2. Obtain an access token from the SAP Fieldglass Authorization Server.
3. Send the access token to an SAP Fieldglass REST API.
4. Refresh the access token, if necessary.
For details on how to perform each of these steps, see the following sections in this guide.
3.1 OAuth2 Service Authentication
There are three authentication options available for the OAuth2 service―client credentials, SAML authentication,
and certicate-based authentication .
Client Credentials Authentication
Client credentials authentication provides a relatively simple mechanism for authentication, using a client ID and
client secret. The client ID is a valid SAP Fieldglass username and the client secret can be either that user's
application password, or, to avoid issues with password rotation, a <license key>, as generated within the SAP
Fieldglass system. Refer to the SAP Fieldglass Conguration Manager to create the license key.
The URL to use for client credentials requests is:
https://<SAP Fieldglass Environment URL>/api/oauth2/v2.0?
grant_type=client_credentials&response_type=token
SAML Authentication
A SAML assertion can be generated for a valid user and passed via a 'SAML Response' parameter (note that this
authentication still uses the client credentials grant type as a framework). Refer to Obtaining an Access Token from
SAP Fieldglass Server [page 11] for more information
The URL to use for SAML authentication request is:
https://<SAP Fieldglass environment URL>/api/oauth2/v2.0?
grant_type=client_credentials&response_type=token
6
PUBLIC
REST API Integration
Conguring Authentication and Authorization
Certicate Authentication
Certicate-based authentication provides a secure mechanism for authentication, eliminating the need for explicit
credentials to be used (note that this authentication still uses the client credentials grant type as a framework). To
leverage certicate authentication, do the following:
• Use a required X509 certicate issued by a trusted Certicate Authority (for example, DigiCert). Contact your
SAP Fieldglass representative for more information.
• Use the correct URL.
Note
The URL includes auth in the sub-domain.
• For a test environment, the URL is in
the following format: https://<env_code>-auth.fgvms.com/ws2/api/oauth2/v2.0?
grant_type=client_credentials&response_type=token. For example: https://xuat-
fgvms.com/api/oauth2/v2.0?grant_type=client_credentials&response_type=token.
Note
Not all test environments are congured. You may need to submit a request to have it congured.
• For U.S. production, the URL is: https://auth.fieldglass.net/api/oauth2/v2.0?
grant_type=client_credentials&response_type=token.
• For EU production, the URL is: https://sso.fieldglass.eu/api/oauth2/v2.0?
grant_type=client_credentials&response_type=token.
To set up the X509 certicate for use in OAuth2 authentication, complete the steps outlined in the Congure X.509
Certicate Authentication [page 7] section within the SAP Fieldglass application. This adds the public certicate
to the application and links it to a user (ensure it's a valid, active user), thus not requiring the credentials to be
supplied as part of the OAuth2 request itself.
3.1.1Congure X.509 Certicate Authentication
Congure SAP Fielglass for X.509 certicate authentication.
Procedure
1. Obtain the public certicate to be used for authentication.
2. Log into SAP Fieldglass with the Conguration Manager role and then choose the Manage Crypto Assets
tile. For detailed information on managing crypto assets in Conguration Manager, see the SAP Fieldglass
Conguration Manager guide.
The Encryption Keys and Certicates page opens.
3. Choose New.
REST API Integration
Conguring Authentication and Authorization
PUBLIC 7
The Create Asset page opens.
4. In the Category list, choose X509.
5. Open the certicate in Notepad, select, and copy all text (including the Begin Certificate and End
Certificate lines), and then paste it into the Public Certicate box.
8
PUBLIC
REST API Integration
Conguring Authentication and Authorization
When you click outside of the box the Begin Certificate and End Certificate lines are no longer visible.
6. In the Notication Email ID eld, enter the email contact to notify when the certicate is about to expire.
REST API Integration
Conguring Authentication and Authorization
PUBLIC 9
7. Choose the Auto-Activate option to make the certicate/asset immediately active and eective in the client’s
vault within the SAP Fieldglass application.
8. Under Extended Key Usage link an object to the certicate. There are a few options for this, however in this case
we're linking a user.
9. After all the relevant elds are populated, choose Create to save the certicate in SAP Fieldglass.
The certicate details display.
10
PUBLIC
REST API Integration
Conguring Authentication and Authorization
3.2 Obtaining an Access Token from SAP Fieldglass Server
Describes how to obtain an access token from the SAP Fieldglass server.
Before your client application can access private data using an SAP Fieldglass REST API, it must request an access
token from the SAP Fieldglass Authorization Server to grant access to the API. A single access token can grant
varying degrees of access to multiple APIs.
After an application obtains an access token, it sends the token to an SAP Fieldglass REST API in an HTTP
authorization header or as part of the request body.
The x-ApplicationKey header is optional for Connector, Identity (SCIM), and Reporting APIs. If you receive an error
for not including an API Key, you can request one from Fieldglass administration.
Obtain Token via Username/Password Credentials
To obtain the access token using username/password credentials, send a x-www-form-urlencoded HTTP GET
request specic to the username/password credentials you received from SAP Fieldglass.
The following sample code illustrates how to obtain the access token with user/password credentials.
Sample Code
sample request for token with user/password credential
POST /api/oauth2/v2.0/token?grant_type=client_credentials&response_type=token
Authorization: Basic {Base64Encoded(user:credential)}
Content-Type: application/x-www-form-urlencoded
X-ApplicationKey: {server provided key}
REST API Integration
Conguring Authentication and Authorization
PUBLIC 11
Sample Code
sample response
{"access_token" : "WDXlKj3TTOn3rpg9GHnZpbKmvj1=",
"token_type" : "Bearer","expires_in" : 7200}
Obtain Token via SAML Authentication
The access token can also be retrieved using SAML authentication. The primary role of SAML in online security is
that it enables you to access multiple Web applications using one set of login credentials.
The SAML assertion is POSTed to the OAuth token endpoint, which in turn processes the assertion and issues an
access_token based upon prior approval of the application. The client doesn't need a client_secret to be
passed to the token endpoint.
The following sample code illustrates how to use SAML to obtain the access token with SAML.
Sample Code
sample request for token with SAML
POST /api/oauth2/v2.0/token?
grant_type=client_credentials&response_type=token&SAMLResponse={Base64Encoded
SAML Assertion}
Authorization: Basic {Base64Encoded(user:credential)}
Content-Type: application/x-www-form-urlencoded
X-ApplicationKey: {server provided key}
Sample Code
sample response
{"access_token" : "WDXlKj3TTOn3rpg9GHnZpbKmvj1=",
"token_type" : "Bearer","expires_in" : 7200}
3.3 Token Expiration
Access tokens have limited lifetimes (the current default is 7200 seconds = 120 minutes).
If your application requires access to an SAP Fieldglass REST API beyond the lifetime of a single access token, it
needs to obtain a new token as outlined in Obtaining an Access Token from SAP Fieldglass Server [page 11].
If you make an API call using an invalid token, you receive a "401 Unauthorized" response back from the server. A
token could be invalid and in need of regeneration for the following reasons:
• The token has expired.
• The user has revoked the permission initially granted to your application.
• You've changed the member permissions (scope) that your application is requesting.
12
PUBLIC
REST API Integration
Conguring Authentication and Authorization
• If a subsequent OAuth 2 ow has generated a new access token, then the previous token is invalidated.
A predictable expiry time isn't the only contributing factor to token invalidation. Be sure that your applications
are coded to properly handle an encounter with a 401 error, by redirecting the user back to the start of the
authorization workow.
REST API Integration
Conguring Authentication and Authorization
PUBLIC 13
4 HTTP Response Codes
Describes how to verify the request data.
The web service returns an HTTP 2xx class response code for a successful request or an HTTP 4xx class (client
error) or 5xx class (server error) response code if a request encounters any errors.
• For an upload request, the call sends formatted data to SAP Fieldglass. The client system receives an HTTP
response from SAP Fieldglass, which indicates the success or failure of the upload. The response is sent as
soon as it's conrmed that SAP Fieldglass has successfully received the le, but it doesn't indicate the success
or failure of processing individual data records.
• For a download request, SAP Fieldglass sends data back to the client/supplier system.
• If the response indicates a failure, the return error code indicates the source of the problem. To check data
errors, users with the appropriate permissions can sign in to the buyer company within SAP Fieldglass to view
the le in the Integration Audit Trail, which provides a record for each individual failed record.
The HTTP response codes are described in the following table. For more information on HTTP response codes,
browse to, http://www.ietf.org/assignments/http-status-codes/http-status-codes.xml.
Response Codes for Successful Requests
Success Code
Message Description Scope
200 OK The request was received suc-
cessfully.
All
Response Codes for Failed Requests
Error Code
Message Description Scope
400 Bad Request
This response is returned if
any of the following conditions
are true:
• The specied URL is inva-
lid.
• The request isn't format-
ted correctly.
• The request is missing a
required eld.
401
Unauthorized User/password or application
key isn't veried.
Token Request
403 Forbidden Token isn't veried. Resource Request
404 Not Found The service being requested
doesn't exist.
All
500 Internal Service not available. All
14 PUBLIC
REST API Integration
HTTP Response Codes
Important Disclaimers and Legal Information
Hyperlinks
Some links are classied by an icon and/or a mouseover text. These links provide additional information.
About the icons:
• Links with the icon
: You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your agreements
with SAP) to this:
• The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.
• SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any
damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.
• Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering an SAP-hosted Web site. By using such links,
you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this information.
Videos Hosted on External Platforms
Some videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any
advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within the
control or responsibility of SAP.
Beta and Other Experimental Features
Experimental features are not part of the ocially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by
SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use the
experimental features in a live operating environment or with data that has not been suciently backed up.
The purpose of experimental features is to get feedback early on, allowing customers and partners to inuence the future product accordingly. By providing your feedback
(e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.
Example Code
Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax and
phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of example
code unless damages have been caused by SAP's gross negligence or willful misconduct.
Bias-Free Language
SAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities, genders,
and abilities.
REST API Integration
Important Disclaimers and Legal Information
PUBLIC 15
www.sap.com/contactsap
© 2024 SAP SE or an SAP aliate company. All rights reserved.
No part of this publication may be reproduced or transmitted in any form
or for any purpose without the express permission of SAP SE or an SAP
aliate company. The information contained herein may be changed
without prior notice.
Some software products marketed by SAP SE and its distributors
contain proprietary software components of other software vendors.
National product specications may vary.
These materials are provided by SAP SE or an SAP aliate company for
informational purposes only, without representation or warranty of any
kind, and SAP or its aliated companies shall not be liable for errors or
omissions with respect to the materials. The only warranties for SAP or
SAP aliate company products and services are those that are set forth
in the express warranty statements accompanying such products and
services, if any. Nothing herein should be construed as constituting an
additional warranty.
SAP and other SAP products and services mentioned herein as well as
their respective logos are trademarks or registered trademarks of SAP
SE (or an SAP aliate company) in Germany and other countries. All
other product and service names mentioned are the trademarks of their
respective companies.
Please see https://www.sap.com/about/legal/trademark.html for
additional trademark information and notices.
Material Number: 20190205
*20190205*
THE BEST RUN
