Reading Time: 15 minutes

Overview

Authentication is a key process when integrating with Mastercard APIs.

Mastercard uses one-legged OAuth 1.0a for authenticating and authorizing client applications. It means every request sent to us must be digitally signed, and only requests with valid signatures created by authorized clients are granted access to our services.

In addition to that, requests with a body must be signed using the Google Request Body Hash extension for OAuth.

In the next sections, you will learn a bit more about the OAuth1 scheme and how to set up keys for your project. You will also find links to our OAuth client libraries, some development tips and answers to frequently asked questions.

OAuth 1.0a Basics

OAuth is a protocol originally published as RFC 5849 and used for securing access to APIs.

Mastercard uses OAuth 1.0a in its simplest form, also known as “One Leg”. This implementation involves one single step, in which we rely on OAuth signatures for server-to-server authentication.

The next few sections give a brief overview of:

• What it means to digitally sign requests in this context
• The format of the expected Authorization header
• What the OAuth credentials for your client application are.

Signed Requests

As explained previously, HTTP requests are signed by client applications. Digital signatures are particularly useful as they guarantee integrity, authenticity and allow for non-repudiation of incoming API calls.

The OAuth signature process:

1. Normalizes requests (URL, body, …) and OAuth parameters into a single string to sign

   The Signature Base String is a consistent reproducible concatenation of the request elements into a single string (…) used as an input in hashing or signing algorithms

2. Signs this string using a client RSA private key and, in our case, the RSA-SHA256 method

3. Adds an Authorization header to the requests (for sending OAuth parameters and the signature along with the request)

Upon reception of the request, the signature base string is recomputed and the RSA signature is verified using the client public key. The signature must be valid and the signed base string and recomputed base string must be identical.

The Authorization Header

OAuth 1.0a uses the standard HTTP Authorization header with the authentication scheme set to OAuth. The header value contains signed OAuth parameters and the request signature value only your application can produce.

Let’s break a real-life example down:

Authorization: OAuth
    oauth_body_hash="94cOcstEzvTvyBcNV94PCbo1b5IA35XgPf5dWR4OamU=",
    oauth_nonce="32lqGrI0f0nQEW85",
    oauth_signature="MhfaStcHU0vlIoeaBLuP14(...)qqd99lI56XuCk8RM5dDA%3D%3D",
    oauth_consumer_key="aXqayIybNdwMnzGIZMAkQYSq(...)139a87746d5b00000000000000",
    oauth_signature_method="RSA-SHA256",
    oauth_timestamp="1558370962",
    oauth_version="1.0"

oauth_body_hash

This element is an extension to OAuth (also known as Google Body Hash) in order to systematically check the integrity of request bodies. It contains a base64-encoded SHA-256 digest of the body.

oauth_nonce and oauth_timestamp

The OAuth nonce is a random string, uniquely generated for each request and also unique within a given time window.
The request timestamp is a positive integer representing the number of seconds since 1970. It must match the current time. In this example, 1558370962 is equivalent to 05/20/2019 @ 4:49pm (UTC).
The timestamp and nonce pair must be unique, or the request will be treated as a replay attack.

oauth_signature

This is the base64-encoded RSA signature of the request, produced using your private signing key. More details in the signed requests section.

oauth_consumer_key

The consumer key is a string identifing your application. More details in the consumer key section.

oauth_signature_method

This parameter indicates the signature method used to compute the oauth_signature value. It must be RSA-SHA256.

oauth_version

The OAuth version used. It must be 1.0.

The Consumer Key

Consumer keys are 97-character identifiers for client applications consuming Mastercard APIs. The consumer key is not a secret (unlike the signing key), but rather a kind of username which appears in the OAuth header value sent with each request (see oauth_consumer_key).

The Signing Key

The signing key is a 2048-bit private RSA key used to generate request signatures and confirms ownership of the consumer key. This private key is part of a public/private key pair generated by you (or your web browser) and whose public key is certified by Mastercard.

Example of unencrypted RSA key (PKCS#1 PEM):

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAx8k7j56VpkzxJT3qb23cYioMZ8VtGSTglwhXjyvags4VsSIH
oCCRd0Ich4UgNfat2adhwoPEw/bER/yaKhfFxiNYyjWruhIbvmzzgcz/w679JTuD
...
TTJVAoGBAMHkR/0+VAR8vvSEEENov43R7jnuggoQej5r9R/gG8UngoJkQ8b3aKGD
fRKHqz7nK1VgT8mh+M63gzL/UW8jSn2c1CbbojK/wU3FuaaRT5eY
-----END RSA PRIVATE KEY-----

Getting Keys for Your Application

As seen above, the OAuth protocol involves a consumer key and a private request signing key. OAuth keys for your projects are set up through your Developer Dashboard and you can manage the keys’ lifecycle from there:

Keys and Environments

There are two different types of keys, depending on the stage of your project:

1. Sandbox keys, which give access to an API sandbox that mimics a live production environment (sandbox.api.mastercard.com)
2. Production keys, which allow an application to access the production environment (api.mastercard.com)

Domain/Server URL may vary depending on the API. Please check the API Reference section of the service documentation for the correct Server URL.

A pre-production environment called MTF (for “Mastercard Test Facility”) is also made available for certain APIs. MTF access will follow the models below depending on the API.

Model 1 - Single API for All Environments

Products using this model have one API for all environments and MTF is accessed using sandbox keys.

Model 2 - Separate MTF and Production APIs

Products using this model have separate APIs for MTF and Production. They will have the same name, except the MTF API will be suffixed with “MTF.” For example: MDES Customer Service and MDES Customer Service MTF. The APIs use the same keys and MTF is accessed using “production” keys.

Creating Keys

Sandbox keys are created as part of the Create Project wizard. You can add additional keys to an existing project by clicking the “Add Key” button on the Sandbox Credentials page. Production keys are created as part of the Request Production Access wizard. You can add additional keys to an existing project by clicking the “Add Key” button on the Production Credentials page.

Two methods are available when creating keys:

Method 1

• A key pair and a certificate signing request (CSR) are generated inside your web browser.
• Mastercard signs and sends your browser back an X509 certificate matching your private key.
• Your browser generates a PKCS#12 key store file securing your private key with the provided passphrase.
• Mastercard generates a new consumer key.

Method 2

• You manually upload a certificate signing request (CSR) generated in your own system.
• Mastercard issues an X509 certificate matching your private key.
• Mastercard generates a new consumer key.
• If needed, you can request the X509 certificate and/or the Mastercard root and intermediate certificates in the Support section.

Renewing Keys

Please reference our Renewing Your Keys guides.

Revoking Keys

To revoke a key, select “Revoke Key” in the Manage menu:

Client Libraries

Mastercard provides client authentication libraries in several languages you can integrate to your project or use as reference OAuth 1.0a implementations:

Download/install
View on GitHub

To get started, simply add to your project the package matching your application development language. You can also refer to the different README.md files for detailed how-to information.

Insomnia Plugin

While integrating with Mastercard APIs, you can also try our plugin for Insomnia. Click the links below to browse the project.

Download/install
View on GitHub

Using Postman

You can use Postman application to call Mastercard APIs. Refer to our Postman Tutorial, which provides detailed how-to information for configuring Postman with the needed authentication.

Development Tips

Error Troubleshooting

In case your request is rejected, you will receive a response with the following fields:

{
    "Source": "{Source}",
    "ReasonCode": "{ReasonCode}",
    "Description": "{Description}",
    "Recoverable": false
}

Here’s a list of common error reason codes and how to fix your request.

INVALID_OAUTH_SBS

The Authorization header is missing from the request or OAuth parameters are missing from the header. See also: The Authorization Header.

INVALID_OAUTH_CONSUMER_KEY

The value for oauth_consumer_key doesn’t conform to the length/format requirements (97-character length, with an exclamation mark in the middle). Make sure you copied the key from your Developer Dashboard by clicking the copy icon next to your consumer key.

INVALID_CLIENT_ID, INVALID_KEY_ID

The value for oauth_consumer_key doesn’t match an existing key or doesn’t have access to the requested API.

INVALID_OAUTH_SIGNATURE_METHOD

The value for oauth_signature_method is invalid or not supported.

INVALID_OAUTH_TIMESTAMP

The value for oauth_timestamp was rejected. Check your clock is accurate (you can use public NTP pools for that). See also: oauth_nonce and oauth_timestamp.

OAUTH_NONCE_USED

The value for oauth_nonce was already used. Check you actually send a different nonce with each new request and that your system is generating enough entropy. See also: oauth_nonce and oauth_timestamp.

INVALID_BODY_HASH

The value for oauth_body_hash is incorrect. You can check:

• The digest algorithm used for computing the oauth_body_hash value matches the one used in oauth_signature_method
• There is no network proxy or equipment updating the request body after the request is sent
• oauth_body_hash contains the digest of an empty string when the request does not have an entity body
• In case the service requires encryption, make sure the payload is encrypted before the request is signed.

AUTHENTICATION_FAILED

The oauth_signature value can’t be verified (wrong signing key, wrong signing base string, …). See also: Signed Requests.

INVALID_KEY

Renew your signing key or create a new one. See also: Getting Keys for Your Application.

Exporting Your Signing Key

Your private signing key is encrypted in a PKCS#12 password-protected file you can directly use with Mastercard client libraries. Here are some commands for exporting RSA keys to alternative formats, for instance in case you want to use them with other libraries.

PKCS#1 PEM

To export your key to a PKCS#1 PEM file (BEGIN RSA PRIVATE KEY), run:

openssl pkcs12 -in key.p12 -nodes | openssl rsa -outform pem -out pkcs1-key.pem

PKCS#8 PEM

To export your key to a PKCS#8 PEM file (BEGIN PRIVATE KEY), run:

openssl pkcs12 -in key.p12 -nodes | openssl pkcs8 -topk8 -nocrypt -out pkcs8-key.pem

Binary DER-encoded PKCS#8

To export your key to a raw PKCS#8 file (binary), run:

openssl pkcs12 -in key.p12 -nodes | openssl rsa -outform der -out pkcs8-key.der

Frequently Asked Questions

Can the Same Keys Be Used for Consuming Multiple APIs?

Yes. The consumer and signing keys are created for a project and projects can reference more than one API. You can manage APIs for your project in the Project APIs’ section of the Summary page.

Will My Consumer Key Change After I Renewed My Signing Key?

The consumer key and signing key are linked together, as you use the signing key to prove you own the consumer key.

• If you simply renew your keys before they expire, your consumer key will stay the same
• If you revoke the keys, then you will have to create new keys and a new consumer key will be generated for you

See also: Getting Keys for Your Application

How Can I Validate My OAuth Implementation?

OAuth 1.0a presents many edge cases that are easy to miss. We strongly encourage you to use existing OAuth libraries rather than implementing the specification yourself. For more information, see the client libraries section above.

Further Reading

• The OAuth 1.0 Protocol
• OAuth Core 1.0 Revision A
• OAuth Request Body Hash