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 Project Dashboard and you can manage the keys’ lifecycle from there. For more information, see OAuth Keys.

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.

Frequently Asked Questions

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.

---

Further Reading

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