# API Basics
source: https://developer.mastercard.com/user-account-management-service/documentation/api-basics/index.md

## Client authentication {#client-authentication}

Warning: **Credential lifecycle:** User Account Management Service supports both OAuth 1.0a and OAuth 2.0. API keys expire after 12 months.  
To renew or rotate a key, navigate to **My Projects \> *`Your-project-name`* \> Credentials \> Sandbox or Production** . The key details are displayed in the corresponding credentials grid. Locate the key you want to update, click the vertical ellipsis (⋮) next to it, and select **Renew key** or **Rotate key**, as appropriate. You do not need to create a new project each time keys are updated.

|          Authentication protocol           |                                                                                                                                      Details                                                                                                                                      |
|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [OAuth 1.0a](https://oauth.net/core/1.0a/) | Mastercard uses OAuth 1.0a with a body hash extension for authenticating API clients. OAuth 1.0a guarantees the integrity and authenticity of incoming API calls and supports non-repudiation of requests.                                                                        |
| [OAuth 2.0](https://oauth.net/2/)          | Mastercard uses [OAuth 2.0 Authorization](https://datatracker.ietf.org/doc/html/rfc6749) with the [Client Credentials Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4), using the FAPI 2.0 security profile (strong client authentication + DPoP token binding). |

Note: **Dual Authentication Support**

User Account Management Service APIs support both OAuth 1.0a and OAuth 2.0 at the project level. A project can be configured to use either protocol individually, or both simultaneously, with no preference or migration requirement implied between them.

### OAuth 1.0a {#oauth-10a}

OAuth requires every API request sent to Mastercard to be digitally signed with an RSA private key. To enable this, generate a private-public RSA key pair consisting of:

* Private key: Used to sign OAuth API requests. Store the private key securely in a password-protected or hardware keystore. It encrypts the signature base string hash, which the server decrypts using the public key.
* Public key: Shared with Mastercard during project setup through a Certificate Signing Request (CSR) or the API key generator. Mastercard uses the public key to validate the OAuth signature included with each API request.

For requests that include a message body, the signature must incorporate the [Google Request Body Hash](https://datatracker.ietf.org/doc/id/draft-eaton-oauth-bodyhash-00.html) extension for OAuth.

OAuth keys are generated during project setup on the Mastercard Developers portal. Additional key pairs can be created later from the project dashboard as needed.
Tip: Do you want to learn more about the authentication scheme Mastercard uses? For that, read our [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-1a-to-access-mastercard-apis/) guide.

### OAuth 2.0 {#oauth-20}

OAuth 2.0 (client credentials) requires your application to request an access token from the authorization server, and call APIs using that access token with DPoP token binding.

Your application needs two sets of key material:

1. An **authentication private key** (from Mastercard Developers) used to sign the client assertion (`private_key_jwt`) for token requests.

2. A **DPoP key pair** generated and stored by your application, used to sign DPoP proofs (per token request and per API call).

* Token requests include a signed client assertion (`private_key_jwt`) and a DPoP proof.
* API calls send `Authorization: DPoP <access_token>` and a fresh DPoP proof per request (including `htm/htu` and `ath`).
* Nonce handling: if you receive `use_dpop_nonce`, retry with the `DPoP-Nonce` value as the `nonce` claim in the next DPoP proof.

Tip: For implementation details and examples, read our [Using OAuth 2.0 to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-2-to-access-mastercard-apis/) guide. To move an existing OAuth 1.0a project to OAuth 2.0, see [Upgrade to OAuth 2.0](https://developer.mastercard.com/user-account-management-service/documentation/upgrade-to-oauth2/index.md).

## Transport encryption {#transport-encryption}

The transport between client applications and Mastercard is secured using [TLS/SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security), which means data is encrypted by default when transmitted across networks. However, Mastercard additionally uses end-to-end payload encryption for sensitive data, such as personally identifiable information (PII). Refer to [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) to learn more about our encryption methods.

### Encryption libraries {#encryption-libraries}

Mastercard has abstracted the encryption scheme into our [client encryption libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#client-libraries), which are available in several of the most used development languages. We highly recommend that you utilize these libraries to encrypt the sensitive data used by this service.

## How to Consume the User Account Management API? {#how-to-consume-the-user-account-management-api}

Note: There are multiple ways of integrating with User Account Management Service:

1. [Using a generated API client (recommended)](https://developer.mastercard.com/user-account-management-service/documentation/api-basics/index.md#generating-your-api-client)
2. [Using a method of your choice](https://developer.mastercard.com/user-account-management-service/documentation/api-basics/index.md#using-a-method-of-your-choice)

### Generating your API client {#generating-your-api-client}

Create customizable API clients from the User Account Management Service specification and let Mastercard open-source client libraries handle the authentication for you. This approach offers more flexibility and is strongly recommended.

For this, follow our [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/) tutorial with the following API specification:
[user-account-management-api-swagger.yaml](https://static.developer.mastercard.com/content/user-account-management-service/swagger/user-account-management-api-swagger.yaml) (104KB)

### Using a method of your choice {#using-a-method-of-your-choice}

User Account Management exposes a REST API: you are free to use the REST/HTTP client of your choice and can still leverage the Mastercard open-source [client authentication](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#client-libraries) and [client encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#client-libraries) libraries for signing your requests and dealing with payload encryption.

For that, refer to the User Account Management Service [REST API Reference](https://developer.mastercard.com/user-account-management-service/documentation/api-reference/index.md).

## Environments {#environments}

The following table describes the two different environments that are available.

| **Environment** |                     Base URL                     |                                                                                                                                 **Description**                                                                                                                                 |
|-----------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox         | `https://sandbox.api.mastercard.com/loyalty/mrs` | Pre-production test environment containing the latest pre-release version of the real APIs, intended for full integration testing prior to moving to production. Use your Sandbox keys to authenticate with this environment. The keys are set up when you create your project. |
| Production      | `https://api.mastercard.com/loyalty/mrs`         | Full production environment containing the latest production API release.                                                                                                                                                                                                       |

## Next Steps {#next-steps}

* Make your first Sandbox call by following the [Quick Start Guide](https://developer.mastercard.com/user-account-management-service/documentation/quick-start-guide/index.md).
* Map your business scenario to endpoints in the [Use Cases](https://developer.mastercard.com/user-account-management-service/documentation/use-cases/index.md) section.
* Generate a client and configure OAuth signing and JWE encryption with the [Integration and Testing](https://developer.mastercard.com/user-account-management-service/documentation/tutorials-and-guides/api-testing-tutorial/index.md) tutorial.
* Validate your integration with the scenarios on the [Testing](https://developer.mastercard.com/user-account-management-service/documentation/testing/index.md) page.