# Quick Start Guide
source: https://developer.mastercard.com/user-account-management-service/documentation/quick-start-guide/index.md

## Overview {#overview}

The User Account Management API service enables customers to manage their rewards programs in real time. This guide outlines the steps required to set up an account, create a project, generate credentials, submit a Sandbox test call to the User Account Management API, and prepare the project for Production access.
Tip: If you want the fastest path to a working Sandbox request, use the [Insomnia Collection](https://developer.mastercard.com/user-account-management-service/documentation/developer-tools/insomnia-collection/index.md) or the [Reference Application](https://developer.mastercard.com/user-account-management-service/documentation/developer-tools/reference-app/index.md). Both let you call the Sandbox without writing your own client first.

### Before you begin {#before-you-begin}

Before you start, ensure that you complete the following prerequisites:

* Create a [Mastercard Developers](https://developer.mastercard.com/) account.
* Ensure that you have a secure location to store the downloaded OAuth and encryption keys.
* Decide how you want to test: Insomnia, the reference application, or your own client.

### Sandbox checklist {#sandbox-checklist}

| # |    Step     |                                                                                                                    What to do                                                                                                                    |
|---|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | Access      | Get access to User Account Management API and create your Mastercard Developers project.                                                                                                                                                         |
| 2 | Credentials | Generate your Sandbox OAuth credentials and record your consumer key.                                                                                                                                                                            |
| 3 | Encryption  | If you are testing any protected-payload flows, complete JWE setup in [API Basics](https://developer.mastercard.com/user-account-management-service/documentation/api-basics/index.md#transport-encryption).                                     |
| 4 | First call  | Send your first Sandbox request by using the Sandbox base URL and OAuth 1.0a signing.                                                                                                                                                            |
| 5 | Validation  | Use the sample response and [Testing](https://developer.mastercard.com/user-account-management-service/documentation/testing/index.md) page to validate test data, positive flows, and negative flows.                                           |
| 6 | Production  | After Sandbox validation is complete, use Step 5 and the [Onboarding Checklist](https://developer.mastercard.com/user-account-management-service/documentation/tutorials-and-guides/onboarding-checklist/index.md) to request Production access. |

## Step 1: Get access to the API {#step-1-get-access-to-the-api}

1. Navigate to [Mastercard Developers](https://developer.mastercard.com/) and click **Sign up** create an account.
2. Activate your account by opening the verification link sent to your email address, and click **Log in**.
3. Enter your credentials and log in to your account.
4. Open your [My Projects](https://developer.mastercard.com/dashboard) page.

## Step 2: Create a project and generate Sandbox credentials {#step-2-create-a-project-and-generate-sandbox-credentials}

You must create a Mastercard Developers project to generate Sandbox credentials. You can start testing in the Sandbox environment immediately after your project credentials are generated. Sandbox credentials provides access to the mocked data, allowing you to validate and test your integration before requesting Production access.

### Project Details {#project-details}

1. Click **Create new project** on your [My Projects](https://developer.mastercard.com/dashboard) page. ![Sandbox project details](https://static.developer.mastercard.com/content/user-account-management-service/uploads/project-details.jpg)
2. Enter a project name.
3. Verify that **Are you creating this project on behalf of a client?** is set to No (this is the default option).
4. In the **Select at least one API** section, select **MRS User Management** from the drop-down list.
5. Click **Proceed**.

### Project Credentials {#project-credentials}

6. In the **Project Credentials** section, select **OAuth 1.0a** for an OAuth 1.0a service or **OAuth 2.0** for an OAuth 2.0 service.
7. Create a key alias and a keystore password for your OAuth keys, store these credentials securely, and click **Proceed** . ![Sandbox project credentials](https://static.developer.mastercard.com/content/user-account-management-service/uploads/project-credentials.jpg)

### Additional Credentials {#additional-credentials}

8. Generate your encryption keys. You may skip this step only if your initial Sandbox validation is limited to unencrypted requests, such as `GET /users/{id}`.
9. If you plan to test any JWE-protected endpoints, complete the encryption key setup before proceeding. For detailed configuration instructions, see [API Basics](https://developer.mastercard.com/user-account-management-service/documentation/api-basics/index.md#transport-encryption).
10. Create a key alias and keystore password for your encryption keys, record them securely, and click **Create Project** . ![Sandbox additional credentials](https://static.developer.mastercard.com/content/user-account-management-service/uploads/additional-credentials.jpg)
11. Download the OAuth 1.0a and encryption keys and store them in a safe place. Then click **Open Project** . ![Project creation confirmation with key download links](https://static.developer.mastercard.com/content/user-account-management-service/uploads/create-your-project.jpg)

##### Save the values that you will need. {#save-the-values-that-you-will-need}

12. On the project dashboard, record the following values:

* Sandbox and Production status
* Authentication consumer key
* Client encryption key fingerprint

![Project dashboard showing Sandbox and Production status and credentials](https://static.developer.mastercard.com/content/user-account-management-service/uploads/project-dashboard.jpg)

## Step 3: Make your first Sandbox request {#step-3-make-your-first-sandbox-request}

Once you have Sandbox credentials, make a simple GET request to confirm that your project is set up correctly.

Before you run the request, make sure you have:

* Your Sandbox consumer key
* The private key used to sign OAuth requests
* A Mastercard OAuth library or signer that generates `oauth_timestamp`, `oauth_nonce`, and `oauth_signature`

This first-call example uses the read-only [Retrieve User](https://developer.mastercard.com/user-account-management-service/documentation/use-cases/user-management/index.md#retrieve-user) endpoint (`GET /users/{id}`). It does not require payload encryption, so you can verify access, OAuth signing, and the Sandbox base URL before moving on to encrypted flows.
Note: For a full client setup, including encryption configuration, see the [API Basics](https://developer.mastercard.com/user-account-management-service/documentation/api-basics/index.md#how-to-consume-the-user-account-management-api) section.

**Example Request (cURL):**

```bash
curl --request GET \
  --url "https://sandbox.api.mastercard.com/loyalty/mrs/users/268810378058708149455458707247?user_id_type=RANCU" \
  --header "Accept: application/json" \
  --header "Authorization: OAuth oauth_consumer_key=\"YOUR_CONSUMER_KEY\", oauth_signature_method=\"RSA-SHA256\", oauth_timestamp=\"1709596800\", oauth_nonce=\"a1b2c3d4e5f6\", oauth_version=\"1.0\", oauth_body_hash=\"47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU=\", oauth_signature=\"YOUR_COMPUTED_SIGNATURE\""
```

> This example shows the required OAuth 1.0a header fields explicitly, but uses placeholders for sensitive values.
> Replace `YOUR_CONSUMER_KEY` with the consumer key from your project and generate `oauth_signature` with a [Mastercard OAuth1 Signer library](https://github.com/Mastercard?q=oauth1-signer). The library also computes `oauth_timestamp`, `oauth_nonce`, and `oauth_body_hash` for you.

**Expected Response (`200 OK`, abbreviated):**

```json
{
  "companyIca": 611532,
  "userId": "268810378058708149455458707247",
  "userIdType": "RANCU",
  "firstName": "John",
  "lastName": "Smith",
  "emailAddress": "abc@example.com",
  "preferredLanguage": "en_US",
  "acceptEmails": false,
  "acceptSms": false,
  "acceptPromotionalInfo": true,
  "address": {
    "addressLine1": "10 Upper Bank Street",
    "city": "London",
    "countryCode": "ENG",
    "postalCode": "63368"
  }
}
```

**How to validate the result:**

* The HTTP status is `200` and the body contains `userId` and `userIdType`.
* If you receive `401`, check your consumer key, signing key, and that you are calling the Sandbox base URL with Sandbox keys.
* For any other error, look up the `ReasonCode` in [Code and Formats](https://developer.mastercard.com/user-account-management-service/documentation/code-and-formats/index.md).

> **Test data:** The Sandbox returns mocked data, so values in the response may differ from the example above. For a negative-flow test, send `user_id_type=BCN`. The API returns `400 Bad Request` with `ReasonCode` `INVALID_INPUT` ("supported value for user_id_type is RANAC or RANCU"). See [Testing](https://developer.mastercard.com/user-account-management-service/documentation/testing/index.md) for additional positive and negative scenarios across all endpoints.

## Step 4: Choose how you want to test and integrate {#step-4-choose-how-you-want-to-test-and-integrate}

After the first Sandbox request succeeds, pick the integration path that matches your workflow:

* **Insomnia:** Use the [Insomnia Collection](https://developer.mastercard.com/user-account-management-service/documentation/developer-tools/insomnia-collection/index.md) page for setup.
* **Reference Application:** Use the [Reference Application](https://developer.mastercard.com/user-account-management-service/documentation/developer-tools/reference-app/index.md) page.
* **Generated client (Java):** Follow the [Integration and Testing tutorial](https://developer.mastercard.com/user-account-management-service/documentation/tutorials-and-guides/api-testing-tutorial/index.md) to generate a client with OpenAPI Generator and configure OAuth signing and JWE encryption.
* **curl or a custom client:** Use the [Testing](https://developer.mastercard.com/user-account-management-service/documentation/testing/index.md) page for test cases and additional examples.

## Step 5: Promote the same project to Production {#step-5-promote-the-same-project-to-production}

After validating your integration in the Sandbox environment, request Production access for the same project.

### Transition your project from Sandbox to Production {#transition-your-project-from-sandbox-to-production}

1. **Open your project in Mastercard Developers**

   Navigate to [My Projects](https://developer.mastercard.com/dashboard) and open the project you used for Sandbox testing.

2. **Request Production access for that project**

   In the project dashboard, click **Request Production Access** .
   ![Project dashboard showing Sandbox and Production status and credentials](https://static.developer.mastercard.com/content/user-account-management-service/uploads/project-dashboard.jpg)

3. **OAuth project keys**
   Create a key alias and a keystore password for your OAuth keys, store these credentials securely, and click **Proceed** .
   ![Production project credentials](https://static.developer.mastercard.com/content/user-account-management-service/uploads/project-credentials-prod.jpg)

4. **Encryption keys**

   Create a key alias and keystore password for your encryption keys, record them securely, and click **Submit** .
   ![Production additional credentials](https://static.developer.mastercard.com/content/user-account-management-service/uploads/additional-credentials-prod.jpg)

5. **Generate or download your Production keys**

   The Sandbox and Production statuses are displayed separately on the project page, allowing you to track the progress of your Production request until it reaches the `Ready` state.

   After your Production access is approved, download the Production OAuth and encryption keys for the project. Keep the Production key material separate from your Sandbox keys.
   ![Project creation confirmation with key download links](https://static.developer.mastercard.com/content/user-account-management-service/uploads/download-your-keys.jpg)

6. **Project dashboard**

   On the project dashboard, record the following values:

   * Sandbox and Production status
   * Authentication consumer key
   * Client encryption key fingerprint

   ![Project dashboard showing Sandbox and Production status and credentials](https://static.developer.mastercard.com/content/user-account-management-service/uploads/project-dashboard-prod.jpg)
7. **Update your application configuration**

   Change the base URL from Sandbox to Production:

   * Sandbox: `https://sandbox.api.mastercard.com/loyalty/mrs`
   * Production: `https://api.mastercard.com/loyalty/mrs`

   Update your application to use the Production consumer key, signing key, and encryption certificates.

Note: OAuth 1.0a authentication and payload encryption work the same way in Sandbox and Production. The primary differences are the Production approval status, the Production credentials, and the Production base URL.

For the complete onboarding process, including stage entry and exit criteria, SLAs, and escalation procedures, see the [Onboarding Checklist](https://developer.mastercard.com/user-account-management-service/documentation/tutorials-and-guides/onboarding-checklist/index.md).

## Next Steps {#next-steps}

After your first Sandbox call succeeds, continue with the documentation that matches your next task:

* [Use Cases](https://developer.mastercard.com/user-account-management-service/documentation/use-cases/index.md) to map business scenarios to endpoints
* [API Reference](https://developer.mastercard.com/user-account-management-service/documentation/api-reference/index.md) for endpoint details
* [API Basics](https://developer.mastercard.com/user-account-management-service/documentation/api-basics/index.md) for authentication, encryption, and client configuration
* [Testing](https://developer.mastercard.com/user-account-management-service/documentation/testing/index.md) for additional request scenarios
* [Onboarding Checklist](https://developer.mastercard.com/user-account-management-service/documentation/tutorials-and-guides/onboarding-checklist/index.md) for the full operational go-live process