OAuth is an open protocol that supports secure authorization in a simple, standard method and decouples authentication from authorization.

Customers who choose to adopt the OAuth protocol for authorization to access CME Group APIs can follow the adoption path outlined below. 

API Service Adoption Steps

...

Step 1

In CME Customer Center, create an OAuth API ID or Convert a Basic Auth API ID to an OAuth API ID.

Create an OAuth ID in CME Customer Center

1. If necessary, create a CME Group Login.
2. Log into CME Customer Center.
3. Follow the steps to Create an API ID. 
   1. For the "Type," select OAuth.

...

CME Group uses OAuth 2.0, a protocol that supports secure decoupled Authentication (Identity verification) and Authorization (Access Level), to access various CME Group Web Service APIs.

OAuth 2.0 Service Adoption Steps

A registered OAuth 2.0 API ID and password is required to access CME Group Web Service APIs.

Authentication with CME OAuth 2.0 Service

Client systems use the OAuth API ID and Password to obtain an authorization token from the CME OAuth 2.0 service.

Authentication and Token retrieval

Client systems must use a HTTP POST method to the following URLs to obtain an authorization token to the relevant environment.

The CME Group token retrieval uses the Client Credentials grant type to request an access token to access a client’s own resources. Other grant types are not supported.

HTTPS Header

For customers using authorization header, the Base64 Encoding is required where secret is the “API ID:Password” (Base64 endcoded), as generated in Customer Center.

• client_id=CME Group OAuth API ID
• client_secret=<secret>

Access Token Request Parameters

• grant_type (required)

The grant_type parameter must be set to client_credentials.

• Client Authorization (required)

Clients must send their CME Group OAuth API ID and password  in the POST request, in client_id and client_secret fields respectively:

client_id=CME Group OAuth API ID

Note that the OAuth API ID and Password is specific to the environment and cannot be used across environments.

POST Method Header and Body parameters

In the HTTP POST method, the following Header parameters are required:

• Content-Type should be set to "application/x-www-form-urlencoded"
• Authorization should be set to "Basic Base64encoded(APIID:Password)"

The Body of the HTTP POST must have grant_type=client_credentials.

Example

The following is an example authorization

...

token request.

POST /as/token.oauth2 HTTP/1.1
Host: auth.cmegroup.com
Content-Type: application/x-www-form-urlencoded
Authorization:Basic 

base64EncodedValue
grant_type=client_credentials

Authentication Responses

Successful Response

If the request for an access token is valid, the authorization server will generate an access token and send back to the client.

The response with an access token will contain the following properties:

• access_token - The access token string to use on requests to the

...

• CME Group Web Service API(s).
• token_type - Defines the type of token, typically just the string “bearer”.
• expires_in - Defines the duration of time, in seconds, until the access token expires and a new token must be obtained

...

• .

...

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"

tokenValue",

  "token_type":"bearer",

  "expires_in":1799,

}

Unsuccessful Response

If the access token request is invalid, such as the OAuth token endpoint URI didn’t match the one used during authorization, then the server will return an error response.

Error responses are returned with an HTTP

...

40x status code, with error and error description parameters.

...

• HTTP 400 errors
• invalid_request– The request is missing a parameter so the server can’t proceed with the request. This may also be returned if the request includes an unsupported parameter or repeats a parameter.
• invalid_grant– The authorization code (or user’s password for the password grant type) is invalid or expired, or the OAuth token endpoint URI given in the authorization grant does not match the OAuth token endpoint URI provided in this access token request.
• unauthorized_client– This client is not authorized to use the requested grant type.
• unsupported_grant_type– Sent if a grant type is requested that the authorization server doesn’t recognize. Unknown grant types also use this specific error code rather than using the invalid_request
• HTTP 401 error

• invalid_client – Client authentication failed, such as if the request contains an invalid client ID or secret.

CME Group supports two optional parameters when returning an error response, error_description and error_uri. These provide more information about the error.

The error_description parameter describes the circumstance of the error. The error_uri provides a link to the API documentation for information about how to correct the specific error that was encountered.

The entire error response is returned as a JSON string, similar to the successful response. Below are examples of a error responses.

...

HTTP 40x response - Client side error. Example error descriptions include:

• Incorrect grant_type value or grant_type is missing.
• Incorrect Content-Type header value or Content-Type is missing.
• Invalid credentials in the Authorization or incorrect encoding.

HTTP 400 Example

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
    "error_description": "grant_type is required",
    "error": "invalid_request"
}

HTTP 400 Example

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
   

 "error": 

"unsupported_grant_type"
}

HTTP

...

401 Example

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error_description": "Invalid client or client credentials.",

  "error": "invalid_client"
}