Lesson 2 of 6
Authentication and CSRF tokens
10 min
Listen to this lesson
A read needs one thing: a user the system accepts. A write needs two: that user, and proof that the request is not a forged one. SAP Gateway protects modifying requests with a cross-site request forgery (CSRF) token. Most "the API is broken" defects raised by new API testers are really missing tokens, lost cookies or the wrong user. This lesson makes the handshake routine.
Who is calling?
| Target | Typical authentication | Notes |
|---|---|---|
| Accelerator Hub sandbox | APIKey header | Personal key; read-only sample data |
| SAP S/4HANA Cloud Public Edition | Communication user (basic auth or certificate) or OAuth via a communication arrangement | The communication scenario decides which APIs the arrangement exposes |
| SAP S/4HANA Private Edition or on-premise (Contoso CMQ, CMR) | Technical or communication user with basic auth, X.509 certificate, or OAuth / SAML through the gateway | Service activated in /IWFND/MAINT_SERVICE (V2) or /IWFND/V4_ADMIN (V4); roles grant access |
| Through SAP Integration Suite API Management | The policy of the API proxy, for example an API key or OAuth token | You test the proxy and the backend separately |
Authentication depends on the target, not on the API.
Add sap-client=100 as a query parameter or header when the system has several clients and the default is not the one you want. At Contoso, CMQ client 100 is the test client; forgetting the client parameter is a classic reason for "business partner not found".
The CSRF handshake
- Send a GET to the service root (or any cheap entity read) with the header
X-CSRF-Token: Fetch. - Read the token from the
X-CSRF-Tokenresponse header and keep the session cookies the response set. - Send the POST, PUT, PATCH, MERGE or DELETE with
X-CSRF-Token: <value>and the same cookies, as the same user. - If you get 403 with the response header
X-CSRF-Token: Required, fetch a new token and retry once.
Worked example: adding an address in CMQ
Wei needs a second address for Great Lakes Fleet Services to test address determination. The call is a POST to A_BusinessPartnerAddress with BusinessPartner 17100001 and the address fields in the body. Without the fetch step, CMQ answers 403. With the token and cookies, it answers 201 Created and returns the new address with its generated AddressID. That ID goes into the test data record, so the cleanup step can find the address again.
| Symptom | Likely cause | Fix |
|---|---|---|
| 403 with X-CSRF-Token: Required | Token missing, stale, or cookies not sent | Fetch again; make sure the client keeps cookies |
| 401 Unauthorized | Wrong user, password, certificate or API key | Check credentials and the target system |
| 403 without the Required header | User authenticated but not authorized | Check roles; on the system, use STAUTHTRACE and /IWFND/ERROR_LOG |
| 404 on the service root | Service not activated, wrong path or wrong client | Check /IWFND/MAINT_SERVICE or /IWFND/V4_ADMIN and sap-client |
Reading authentication and authorization failures.
- Is the status 401?Yes → credentials, API key or certificate are wrong for this system · No → next question
- Is it 403 with X-CSRF-Token: Required?Yes → fetch a new token and keep the cookies · No → next question
- Is it 403 without that header?Yes → authorization: trace the user's checks · No → next question
- Is it 404?Yes → service path, activation, key or sap-client · No → read the error payload
Communication arrangements and scenarios
In SAP S/4HANA Cloud, and increasingly in Private Edition for released APIs, access to an API is granted through a communication arrangement based on a communication scenario. The scenario bundles the inbound services an integration needs; the arrangement binds it to a communication system and a communication user. For the business partner API the scenario is SAP_COM_0008 (business partner, customer and supplier integration). Check the scenario ID for each API on its Accelerator Hub page. For a tester this matters because a 403 or 404 can simply mean the API is not in the arrangement the interface uses, and that is a configuration defect, not an API defect.
Most HTTP clients let you script the CSRF handshake as a pre-request step: send the fetch, store the token in a variable, and add it to every modifying request in the collection. Do this once and never copy tokens by hand again. Make sure the client keeps cookies between requests; some command-line runners need an explicit cookie jar.
What would you do?
Ravi's automated API check creates an address in CMR every night. It passed for weeks, then started failing with 403 after the test runner was moved to a new agent that runs each request in a fresh process. What is the most likely cause?
- Authentication depends on the target: APIKey in the sandbox, communication or technical users and OAuth on real systems.
- Fetch the CSRF token with a GET and X-CSRF-Token: Fetch; send it back with the same cookies on every write.
- 403 with X-CSRF-Token: Required means a token problem; 403 without it usually means authorization.
- Test with the production user type, and keep negative tests.
Check your understanding · not graded
Lesson check
1. Which header value requests a CSRF token?
2. What must accompany the token on the write request?
3. What does 403 with X-CSRF-Token: Required mean?
4. Why test APIs with the communication user rather than a dialog user?