Skip to main content

OAuth authentication

The Commerce platform APIs use OAuth 2.0 authentication.

Tip

Prior to performing the procedures for OAuth 2.0 integration, download the appropriate authentication utility for certificate and token generation.

In this guide, you will learn how to use OAuth 2.0 to authenticate your API calls to the Commerce platform. The steps to use OAuth authentication are the same and must be performed for both the testing and production environments. The following items, however, are different and must be unique for each environment:

  • client certificates
  • client IDs
  • public certificates
  • private keys
  • API endpoints

The URI used to create access tokens is the same for both environments.

OAuth 2.0 authentication process

To use OAuth 2.0 authentication for testing environment access, perform the following steps. The rest of the article provides detailed instructions on each step.

  1. Generate a certificate signing request (CSR) or certificate using either the J.P. Morgan authentication utility or OpenSSL, and provide the CSR/cert to your J.P. Morgan Payments Representative via email. Your J.P. Morgan Payments Representative then provides your client ID, resource ID, token Uniform Resource Indicator (URI), and certificate (if you provided a CSR).
  2. Use your private key and certificate to sign a JSON Web Token (JWT).
  3. Send a request to the J.P. Morgan Token URI to create an access token, which is valid for 8 hours.
  4. Use the access token to send requests to the Commerce platform testing environment endpoints.
  5. Repeat steps 1-3 to access the Commerce platform production environment endpoints.

Generate a certificate

Generate a certificate signing request, self-signed certificate, or authority-signed certificate. You can do so by either using the J.P. Morgan authentication utility or using OpenSSL. The following table details what certificates are approved for test and production environments:

Approved certificates
Environment CSR Self-signed certificate CA-signed certificate
Test Yes Yes Yes
Production Yes No Yes

CA-signed certificates must be signed by one of the following J.P. Morgan approved certificate authorities: 

  • Entrust 
  • DigiCert (formerly Symantec) 
  • GoDaddy Group 
  • GlobalSign 
  • Thawte

Follow your selected certificate authority's instructions on generating a certificate.

Attention

If you are using a CA signed X.509 certificate, it is your responsibility to ensure the certificate is updated before it expires. New certificates need to be provided to J.P. Morgan to prevent service interruptions. If you are using a CSR, J.P. Morgan will reach out to request an updated CSR prior to the certificate expiring.

Use the authentication utility

If you choose to generate a certificate using the authentication utility, each language's authentication utility is found in the sample-authentication-code directory of the authentication repository.

Generate a CSR or self-signed certificate

  1. Download and unzip or fork and clone the J.P. Morgan authentication utility. Open the terminal (or shell), navigate to the sample-authentication-code directory, and then install any required dependencies. You'll also find a README file that has additional information.
  2. Run the generate certificates file to generate a client certificate request and a self-signed certificate.
  3. The script then prompts you to enter your country (two-letter ISO 3166-1 code), state/province (abbreviated or fully spelled), locality/city, organization (legal entity name which owns the domain being secured), organization unit (internal department name), and common name (the fully qualified domain name being secured). This information will be used to construct your client certificate request and self-signed certificate.
Plaintext
Country Name (2 letter ISO code): US 
State or Province Name: FL 
Locality Name (eg, city): Tampa 
Organization Name (eg, company): SampleOrganization 
Organizational Unit Name (eg, section): SampleUnit 
Common Name (eg, fully qualified domain name): www.example.com

Use OpenSSL

If you don't want to use the authentication utility, use OpenSSL to generate a private-public key pair, as well as a CSR.

1. Run the following OpenSSL command after updating the angle bracketed variables as follows:

  • <filename.>txt — Name the public key to be generated, which needs to be zipped and shared with J.P. Morgan.
  • <filename>.key — Name the file that will contain your private key. Do not send it to J.P. Morgan.
  • <Country> — This variable must be a two-letter ISO code.
  • <State> — This variable can be the abbreviated or fully spelled name of your province or state.
  • <City> — This variable must be your city or locality.
  • <Organization> — This variable must be the legal name of the entity which owns your common name.
  • <Organization Unit> — This variable should be the internal department name which owns your common name.
  • <Common Name> — This variable must be your fully qualified domain name.
Plaintext
openssl req -new -newkey rsa:2048 -nodes -out <filename>.txt -keyout <filename>.key -subj "/C=<Country>/ST=<State>/L=<City>/O=<Organization>/OU=<Organization Unit>/CN=<Common Name>"

2. Run the following OpenSSL command to generate a CSR using the private key. Be sure to update the angle bracketed variables the same as the previous list, in addition to:

  • <privateKeyFilename>.key — This is the name of the private key you just created.
  • <csrFilename>.csr — Name the CSR file to be generated and that you will zip and share with J.P. Morgan.
Plaintext
openssl req -new -key <privateKeyFilename>.key -out <csrFilename>.csr -subj "/C=<Country>/ST=<State>/L=<City>/O=<Organization>/OU=<Organization Unit>/CN=<Common Name>"

3. Zip and email the output of step 2 to J.P Morgan.

Share your CSR or client certificate

Email your CSR or certificate to your J.P. Morgan Payments Representative. 

Once we receive your CSR/cert, we create an OAuth profile and generate a client ID and (if you sent us a CSR) a signed certificate. We then email the client ID, signed certificate (if applicable), resource ID, and token URI to you. 

Generate an access token

Once you have received the client ID, signed certificate (if applicable), resource ID, and token URI from your J.P. Morgan Payments Representative, you must create an access token prior to making any requests to the API.

You can generate an access token one of two ways:

Use the authentication utility

In this option, use the authentication utility to sign a JWT and call the API to create an access token.

Update variables

Each authentication utility has a slightly different method of handling variables. Update the appropriate variables with your API credentials and file paths.

Tip

If you use OpenSSL to generate your keys and certificates, be sure to update the file path variables.

Create an access token

Run the get access token file of the authentication utility, which signs the JWT and calls the token URI.

The following is an example of a returned access_token using the JS authentication utility:

Json
{ 
"access_token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI9IwJEYXo0Ke5jZ0Y2eHRsY0RfVDl6bzFUU1BaCDJ8.eyJhdWQiOiJKU E1DOlVSSTpSUy0xMDMyNTctMjQ5KWEtQ29ubmVjdFBheW1lbnRzVWF0QXBwLVVBVCIsImlzcyI6Imh0dHA6Ly9pZGF1YXQuanBt b3JnYW5jaGFzZS5jb20vYWRmcy9zZXJ2aWNlcy90cnVzdCIsImlhdCI6MTU3NDM3MzU3NCwiZXhwIjoxNTc0NDAyMzc0LCJKUE1 DSWRlbnRpZmllciI6IkY2Nzc4NDQiLCJSb2xlIjpbIk1TQ29ubmVjdFVhdENvbnRyb2xHcm91cC0yNDk0MS0xMDMyNTctVUFUIi wiQ29ubmVjdFBheW1lbnRzVWF0QXBwX0FMTC0yNDk0MS0xMDMyNTctVUFUIl0sIkNsaWVudElQQWRkcmVzcyI6IjE3Mi4yNi4xN jMuMjMyIiwiYXV0aG1ldGhvZCI6WyJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvYXV0 aGVudGljYXRpb25tZXRob2QvdGxzY2xpZW50IiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW5 0aXR5L2F1dGhlbnJqY2F0aW9ubWV0aG9kL3g1MDkiXSwiYXBwdHlwZSI6IkNvbmZpZGVudGlhbCIsImFwcGlkIjoiQ0MtMTAzMj U3LUY2Nzc4NDQtMzgzNzEtVUFUIiwiYXV0aF90aW1lIjoiMjAxOS0xMS0yMVQyMTo1OTozNC4wMTlaIiwidmVyIjoiMS4wIn0.O 1LeuTzHpCZ9eja4sBgpl9Ypf71s747alq0uOQ4XJ-
198AKRzvPzeltJotl063qfxShHrfpP1Z9jBh2bt7iu8yh3EeUZc_dpl7cjAlllZSAmKuDyP8d2evHxp0P4gfIAixTeaNBIwwbiAu-CczN30g2RgQvWyTqhRpw2uLXvTFR4QnVSztgcAgKqq-
PmMYXACNziWqzUMGsHEK8Qw5eQP0v6pXdx4LLiJBxNIc0R1OFN-
GT8X8bsQVasHF0ASBG9UuawbpV6h3qoySgZgfDjOpJcpAHsdz4xDKNkOsMfLGah51wgNumt4wz-
S6XYkWPgobe4TOqk9FdWnimgruaOg",
"token_type": "bearer",
"expires_in": 28800
}

Use the access token

Use the access token as the bearer token to send Hypertext Transfer Protocol (HTTP) requests to the Commerce platform APIs.

Note

An expired token returns an HTTP status of 401. Create a new token before proceeding.

Use an HTTP request

If you do not want to create a token using the authentication utility, sign a JWT (recommended via authentication utility) and call the token URI to create an access token. You can write your own code to sign a JWT, but our instructions go over using the authentication utility since that is the recommended method.

Update variables

Each authentication utility has a slightly different method of handling variables. Update the appropriate variables with your API credentials and file paths.

Tip

If you use OpenSSL to generate your keys and certificates, be sure to update the file path variables.

Sign a JWT

To sign a JWT, run the get JWT file of the authentication utility. The output is used in the header field client_assertion during the next step.

The following is an example of JWT returned from the JS authentication utility:

Plaintext
JWT: eyJhbGciOiJSUzI1NiVmInR5cCI6IkpXVCIsImtpZCI6IkE0RDAwOTIyOEUxNEJEMDZCOUJGMzI0Qjg4 
QTUzOTE4MzEwQjM5NjkifQ.eyJqdGkiOiIxMjM0NSIsImlhdCI6MTU3NDM2OTY2OSwiZXhwIjoxNTc0N 
DEyODY5LCJhdWQiOiJodHRwczovL2lkYXVhdC5qcG1ckmdhbmNaYXNlLmNvbS9hZGZzL29hdXRoMi90b 2tlbiIsImlzcyI6IkNDLTEwMzI1Ny1GNjc3ODQ0LTM4MzcxLVVBVCIsInN1YiI6IkNDLTEwMzI1Ny1GN jc3ODQ0LTM4MzcxLVVBVCJ9.gWcdqXyifWvpZlaI5gxOVyEFFDZA0dJaOVTXJu28S9p4uFG-1L8D6Wx3 6mtfZ2EZqe3SMIVaQe-yVSZYVvJ7_58NKBCIvI6IMkguQ5sP5LiyCs34Nt2BhqOibu1hCrxqp45piHX4 
1BzNki-KklAx1OICDKp3RkhhykLOV2WU5bOj6HrlIjVvJ6hNkLDL5jRY3UgBDhRa7-xzO9vJ2wvxNJGJ F9pVHOgYIwNbvifvfC_nvxxs1GaA8gGWbPdNO4Q0nj5_pTjHhIbL3GrkXmSdp7a6JHOzS1gfYOz9MHHu h9QIF2cqpBZipiLdjWL84ft6jI0_5kpotMGkHsNZMX4RqB

Create access token

Send a POST HTTP request to the token URI with the headers and body as follows:

Headers

  • content-type: application/x-www-form-urlencoded

Body

  • grant_type — client_credentials.
  • client_id — This is provided by J.P. Morgan.
  • client_assertion_type — urn:ietf:params:oauth:client-assertiontype:jwt-bearer.
  • client_assertion — This is the <signed JWT>. Ensure it does not contain any white spaces or new lines.
  • resource — This is provided by J.P. Morgan.

The following is an example of access_token returned by the JS authentication utility:

Json
{ 
"access_token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI9IwJEYXo0Ke5jZ0Y2eHRsY0RfVDl6bzFUU1BaCDJ8.eyJhdWQiOiJKU E1DOlVSSTpSUy0xMDMyNTctMjQ5KWEtQ29ubmVjdFBheW1lbnRzVWF0QXBwLVVBVCIsImlzcyI6Imh0dHA6Ly9pZGF1YXQuanBt b3JnYW5jaGFzZS5jb20vYWRmcy9zZXJ2aWNlcy90cnVzdCIsImlhdCI6MTU3NDM3MzU3NCwiZXhwIjoxNTc0NDAyMzc0LCJKUE1 DSWRlbnRpZmllciI6IkY2Nzc4NDQiLCJSb2xlIjpbIk1TQ29ubmVjdFVhdENvbnRyb2xHcm91cC0yNDk0MS0xMDMyNTctVUFUIi wiQ29ubmVjdFBheW1lbnRzVWF0QXBwX0FMTC0yNDk0MS0xMDMyNTctVUFUIl0sIkNsaWVudElQQWRkcmVzcyI6IjE3Mi4yNi4xN jMuMjMyIiwiYXV0aG1ldGhvZCI6WyJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvYXV0 aGVudGljYXRpb25tZXRob2QvdGxzY2xpZW50IiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW5 0aXR5L2F1dGhlbnJqY2F0aW9ubWV0aG9kL3g1MDkiXSwiYXBwdHlwZSI6IkNvbmZpZGVudGlhbCIsImFwcGlkIjoiQ0MtMTAzMj U3LUY2Nzc4NDQtMzgzNzEtVUFUIiwiYXV0aF90aW1lIjoiMjAxOS0xMS0yMVQyMTo1OTozNC4wMTlaIiwidmVyIjoiMS4wIn0.O 1LeuTzHpCZ9eja4sBgpl9Ypf71s747alq0uOQ4XJ-
198AKRzvPzeltJotl063qfxShHrfpP1Z9jBh2bt7iu8yh3EeUZc_dpl7cjAlllZSAmKuDyP8d2evHxp0P4gfIAixTeaNBIwwbiAu-CczN30g2RgQvWyTqhRpw2uLXvTFR4QnVSztgcAgKqq-
PmMYXACNziWqzUMGsHEK8Qw5eQP0v6pXdx4LLiJBxNIc0R1OFN-
GT8X8bsQVasHF0ASBG9UuawbpV6h3qoySgZgfDjOpJcpAHsdz4xDKNkOsMfLGah51wgNumt4wz-
S6XYkWPgobe4TOqk9FdWnimgruaOg",
"token_type": "bearer",
"expires_in": 28800
}

Use the access token

To send HTTP requests to Commerce platform APIs, use the access token as the bearer token.

Note

An expired token returns an HTTP status of 401. Create a new token before proceeding.

Deploy to production

Once you've generated a certificate and an access token for our testing environment, you'll be ready to build your Commerce platform integration. Be sure to build out the functionality showcased by the authentication utility as part of this integration. Once you follow the steps described in this article for our production environment, you'll be ready to authenticate API calls to our production endpoints.