# API Basics
source: https://developer.mastercard.com/locations/documentation/api-basics/index.md

## API Security {#api-security}

### Client Authentication {#client-authentication}

Mastercard uses [OAuth 1.0a with a body hash extension](https://oauth.net/core/1.0a/) for authenticating the API clients. This requires every request
you send to Mastercard to be signed with an RSA private key. A private-public RSA key pair must be generated consisting of:

1. A **private key** for the OAuth signature for API requests. It is recommended to keep the private key in a password-protected or hardware keystore.   
2. A **public key** is shared with Mastercard during the project setup process through either a certificate signing request (CSR) or the API Key Generator. Mastercard will use the public key to verify the OAuth signature provided on every API call.

Requests with a body must be signed using the Google request body hash extension for OAuth.
The OAuth keys for your project can be set up on your project dashboard here ([Developer Dashboard](https://developer.mastercard.com/dashboard)) after you create a project.
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/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/) guide.

### 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. Mastercard's encryption scheme is typically used for encrypting sensitive data such as personally identifiable information (PII). Payload encryption is not required for this API.

### Key Management {#key-management}

* Store the `.p12` keystore in a hardware security module or OS-level keystore. Never commit it to source control or embed it in client-side code.
* Protect the keystore with a strong password held in a secrets manager, not in configuration files.
* Rotate keys at least annually, or immediately after any suspected compromise, by uploading a new certificate signing request (CSR) from your [project dashboard](https://developer.mastercard.com/dashboard).
* Sandbox and Production keys are distinct. Never reuse a Sandbox key in Production, or the reverse.
* Grant key access on a least-privilege basis and revoke credentials when a team member or service is decommissioned.

### Data Handling {#data-handling}

* ATM Locations responses contain location data only. They do not include cardholder data or payment credentials.
* Do not log full request or response payloads that contain OAuth headers, consumer keys, or private key material. Redact the `Authorization` header before logging.
* Retain and cache ATM data only as permitted by your Mastercard agreement, and apply your organisation's data retention policy.
* Always call the API over HTTPS. Reject any connection that does not negotiate TLS 1.2 or higher.

Warning: If you believe a private key or consumer key has been exposed, rotate it immediately from the project dashboard and contact [apisupport@mastercard.com](mailto:apisupport@mastercard.com).

## How to Consume the API? {#how-to-consume-the-api}

### Generating your own ATM Locations API client {#generating-your-own-atm-locations-api-client}

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

To learn how to generate your own client, please follow our guide: [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 [ATM Locations API specification file](https://static.developer.mastercard.com/content/locations/swagger/atms-locations-api-spec.yaml).

## Environments {#environments}

### Sandbox {#sandbox}

The ATM Locations API Sandbox is an environment that mirrors the production environment. It is a shared environment that everyone who creates a project has access to. All data in the sandbox is test data but representative of what is available in production, it is useful to understand the structure, and nature, of the data that is available with the service.

All endpoints, and data elements are available in Sandbox by default and it is free to use. The only limitation is that the data is entirely mocked and cannot be used in production solutions.

#### Base URL for Sandbox endpoint {#base-url-for-sandbox-endpoint}

* Sandbox

```Sandbox
https://sandbox.api.mastercard.com/locations/atms
```

### Production {#production}

To learn about the end-to-end process to move from Sandbox to Production see [Move to Production](https://developer.mastercard.com/locations/documentation/quick-start-guide/index.md#go-live) guide. We offer a free trial of the ATMs Locations APIs before requesting production access to initiate the contracting process in parallel with your other onboarding steps.

#### Base URL for Production endpoint {#base-url-for-production-endpoint}

* Production

```Production
https://api.mastercard.com/locations/atms
```

## Next Steps {#next-steps}

### API Status {#api-status}

The ATM Locations API uses synthetic monitoring to continuously verify that the API is available and functioning as expected. This information is publicly available, allowing you to check up-time and review any recent issues. Check the [Status Page](https://developer.mastercard.com/api-status?environment=production&service=Location%20Intelligence-ATM%20Locations) to view this information.

### Developer Tooling {#developer-tooling}

We provide a set of developer tools to help you integrate with the API more easily and get the most value from the account range data. These tools give you a head start when building your connection. For details, see [Developer Tools](https://developer.mastercard.com/locations/documentation/developer-tools/index.md)