Understanding Apto APIs

Before getting started testing your program in sandbox, let's take a moment to understand authentication and objects in Apto's APIs.

API authentication#

Apto uses API keys to control access to our APIs. Keys consist of a public component and a private component, which act like a username and password. The Core API and Mobile API handle keys differently.

note

Keys are always associated with sandbox or production. Sandbox keys will not work in production, and vice versa.

Mobile API authentication#

The Mobile API creates a secure connection between an individual cardholder’s application and their specific data within Apto’s platform. We provide a public key that identifies your program, and the cardholder completes the authentications with a session token, which is generated by the API once the cardholder verifies themself via their primary credential, and which serves the private key.

  • Public key: This string of characters identifies your card program.
  • Private key: When your users authenticate themselves, they get a session token that serves as the private key.
curl --location --request POST {ENDPOINT} \
--header 'Api-Key: Bearer {PUBLIC_KEY}' \
--header 'Authorization: {PRIVATE_KEY}' \
--header 'Content-Type: application/json' \

Your Mobile API key is generated by Apto automatically when you create your account. You can only have one public Mobile API key. Learn how to find your public Mobile API key.

Core API authentication#

With the Core API, information will flow from the Apto platform to your backend. You can then pass it on to the cardholder’s mobile application, with private API keys used to secure the communication. These API keys are a pair of values that you can generate in Dashboard.

  • Public key: This key is sometimes called the API Key. It always starts with pk_live_.
  • Private key: Sometimes called an API Secret, this key always starts with sk_live_.
  • In basic HTTP authentication, a request contains a header field in the form of Authorization: Basic <credentials>, where credentials are the Base64 encoding of a public Core API key and its private API secret joined by a colon.
  • You can have more than one set of Core API keys. Learn how to create Core API keys.
  • For Instant Issuance programs, Core API access is limited in production.
curl --location --request POST {ENDPOINT} \
--header 'Authorization: Basic $(echo -n <my_public_key>:<my_secret_key> | base64)' \
--header 'Content-Type: application/json' \
Caution

In production, your private Core API secrets provide access to all your cardholders’ data. Do not make these values public or use them outside of your private infrastructure. Never use production Core API credentials in user-facing applications.

API objects#

Apto’s APIs are built around three main objects:

  1. Cardholder - A user's entity within the Apto platform. All Know Your Customer (KYC) information is stored here, and KYC is performed against the cardholder. Depending on your program configuration, the cardholder can either be your company or your users.
  2. Card - The card itself, which is an externally-facing payment instrument, either virtual or physical, for interacting with funds on the associated balance. All Apto cards are tied to a balance account. In consumer programs, creating a cardholder automatically issues a card and accompanying balance. In commercial programs, additional cards can be created to draw upon corporate accounts.
  3. Transaction - The payments made by a cardholder with their card as well as other transaction events such as refunds. In general, for a transaction to be authorized, the associated card must have sufficient balance to cover the transaction amount. Though in enterprise programs, you can be involved in the authorization process via our Transaction Auth API in order to automatically approve or deny authorization when a user attempts to pay with their card. Learn more about the transaction authorization process.

An additional concept is the balance account, which represents the balance / store of funds associated with and accessed by a given card.

Instant Issuance is a funds good debit program in which there is a 1:1:1 mapping between a cardholder, their balance account, and their card. That is, creating a cardholder automatically creates a single balance account for them and a single card that can then draw upon this balance. And, cardholders can only ever have one card.

In Enterprise programs, Apto is able to support multiple cards and balances per cardholder. With our Corporations API, we can also support scenarios where multiple cards draw upon the same corporate balance.

For more detailed information, checkout our Mobile API documentation and Core API documentation.