Margin Service API - Authentication and Entitlement
- Space Sync for Confluence
This section contains information pertaining to user authentication and entitlement within the Margin Service API.
Authentication, New Method
On or before February 25, 2025 in the test/NR environment and March 28, 2025 in the production environment, all CORE API users are required to pass a more secure form of basic authentication when interacting with the API.
To initiate a session with CORE's API, the client must make a request passing in the Authorization parameters within the HTTP request headers. These credentials must be a valid CME Group base64 encoded API ID.
For users testing in the API management application Postman, pass an Authorization token instead of username and password. To do this, users can go to the Postman “Authorization” tab and select “Basic Auth”. Then add a username and password. This will add the Authorization token with the encoded value in headers automatically for all subsequent requests.
Examples for users connecting to the API programmatically:
Java Implementation - Remove username and password from headers and pass the following.
public String encodeBase64(String userId, String password) {
String authKey = userId + ":" + password;
String encodedAuthKey = Base64.getEncoder().encodeToString(authKey.getBytes(StandardCharsets.UTF_8));
return "Basic " + encodedAuthKey;
}
String encoded = encodeBase64(userId, password);
httpServletRequest.setAttribute("Authorization", encoded);Python Implementation
import requests
from base64 import b64encode
# Authorization token: we need to base 64 encode it
# and then decode it to acsii as python 3 stores it as a byte string
def basic_auth(username, password):
token = b64encode(f"{username}:{password}".encode('utf-8')).decode("ascii")
return f'Basic {token}'
username = "username"
password = "password"
url = "https://posttrade.api.uat.cmegroup.com/MarginServiceApi//portfolios"
payload = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<ns2:portfolioReq xmlns:ns2=\"http://cmegroup.com/schema/core/1.1\">\n <portfolio desc=\"My Desc\" name=\"My Name\" rptCcy=\"AUD\" id=\"0\">\n <entities clrMbrFirmId=\"My Firm\" custAcctId=\"My Account\"/>\n </portfolio>\n</ns2:portfolioReq>"
headers = {
'Authorization': basic_auth(username, password),
'Content-Type': 'application/xml',
'Cookie': 'SESSION=[insert cookie]',
'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.0.0 Safari/537.36',
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)Note: Content-Type headers should not be passed for any GET/DELETE API calls but can be used in POST/PUT calls.
To avoid HTTP 403 errors ensure all requests pass "User-Agent" as a header, even if passing an empty string i.e. 'User-Agent': '
Authentication, Old Method
This method of Basic Auth authentication is possible through February 28, 2025 in the test/NR environment and through March 25, 2025 in the production environment. Please see Authentication, New Method for new guidance.
To initiate a session with CORE's API, the client must make a request passing in the username and password parameters within the HTTP request headers. These credentials must be a valid CME Group Login or API ID.
Upon successful login, the Margin Service API will return a session ID in the sessionId HTTP response header.
Entitlement
Entitlement for API calls are determined by the CME Group API ID used for authentication and by completing a standard API license with CME.
To create a new API ID, create a login at https://login.cmegroup.com/sso/navmenu.action, then follow steps to create an API ID. Please reach out to posttradeservices@cmegroup.com to discuss licensing access to the API.
Entitlements are provisioned by CME CORE system administrators. Entitlement management is not available through the Margin Service API.
Authenticating to the API - Frequently Asked Questions
User receives 500 Error “RegularExpressionProtestion” (example below)for GET and DELETE API calls.
Resolution: Content-Type headers should not be passed for any GET/DELETE API calls. If you are using Postman, Go to headers and unselect Content-Type.
User receives error message '
There was a problem with your request. Please try again, or contact the CME CORE Support Team.' for POST/PUT API calls.
Resolution: Content-Type headers with value “application/xml” is required for POST/PUT API calls. If you are using Postman, then Go to headers and select Content-Type.
User receives HTTP 403 Error.
Resolution: Specify a “User-Agent” header to avoid an HTTP 403 response. It can be passed as an empty string.
Python example:
headers = {
'Authorization': basic_auth(username, password),
'Content-Type': 'application/xml',
'Cookie': 'SESSION=[insert cookie]',
'User-Agent': '',
}
Postman example:
User receives 500 Error code - “PayloadParsingError” response to GET API calls (example below).
Resolution: The new URLs requires updated version ="1.0" for the payload. Update the version in the payload as below:
<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>
User receives authorization failed error with reason code “INVALID_CREDENTIALS.”
Resolution: CORE API users are required to pass a more secure form of basic authentication when interacting with the API with the new authentication method. To initiate a session, pass the Authorization parameter within the HTTP request headers. These credentials must be a valid CME Group base64 encoded. See Java and Python examples in the online documentation here.
Postman users - Change the “Authorization” settings before initiating the request. in the “Authorization” tab, select “Basic Auth”, and add username and password. This will add
the Authorization token with the encoded value in headers automatically.
User receives environment-related errors with reason “NOTFOUND.”
Resolution: If your are getting NOTFOUND error for the environment URL then update the URL. New URLs are listed below for both test and Production environments.
Test Environment URLs:
Production Environment URLs:
Function | New Test Environment URL |
|---|---|
Margins | |
Transactions | https://posttrade.api.cmegroup.com/MarginServiceApi/transactions |
Portfolios | https://posttrade.api.cmegroup.com/MarginServiceApi/portfolios |
Optimize | https://posttrade.api.cmegroup.com/MarginServiceApi/optimize |
All In One | https://posttrade.api.cmegroup.com/MarginServiceApi/margins?complete=true |
Related content
How was your Client Systems Wiki Experience? Submit Feedback
Copyright © 2024 CME Group Inc. All rights reserved.