API Basics

Learn about the Lithic API.


An API key is required to get started. Generate one on the account page of the Lithic Dashboard.

Requests are authenticated with an API (secret) key with the following request header:

"Authorization: YOUR_API_KEY"


curl --request GET \
     --url 'https://api.lithic.com/v1/cards' \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR_API_KEY'


You can use this information to diagnose failed transactions and fine-tune your exception-handling capabilities.


[query] is not a valid parameterA parameter in the query given in the request does not match the valid queries for the endpoint


User has not been authenticatedInvalid or missing API key
API key is not activeThe API key used is no longer active
Could not find API keyThe API key provided is not associated with any user
Please provide API key in Authorization headerThe Authorization header is not in the request
Please provide API key in the form Authorization: [api-key]The Authorization header is not formatted properly
Insufficient Privileges. Issuing API key requiredWrite access requires an Issuing API key. Please contact [email protected]
Insufficient privileges to create virtual cards.Creating virtual cards requires an additional privilegePlease contact [email protected]


Authorization failed (in simulation)An authorization fails when simulating an authorization


Rate limited, too many requests per secondUser has exceeded their per second rate limit
Rate limited, reached daily limitUser has exceeded their daily rate limit
Rate limited, too many keys triedOne IP has queried too many different API keys


Internal Server ErrorThere was a processing error on the server-side.

General Notes

  • Each entity is identified by its token.
  • HTTP bodies must be valid JSON and the request header Content-Type must be application/json.
  • Amounts are all integers. They are represented in the smallest unit of the associated currency (e.g., amount of 100 in USD is $1) unless specified otherwise.
  • Any field we don’t have data for will show up as empty.
  • All dates are RFC 3339 unless specified otherwise.
  • Additional fields may be added to API response payloads. API users should ensure that any integrations and use of these responses can handle new fields at any time.
  • API GET responses are returned in a pagination wrapper in the form:
  "data": [
  "page": Integer,
  "total_entries": Integer,
  "total_pages": Integer

Versioning and backwards compatibility

The Lithic API will not make backwards-incompatible changes such as removing a field from the API without reaching out to you first. We're continually making backwards-compatible changes to the API. Examples of things we do not consider "breaking" include:

  1. Adding new optional request parameters to existing API methods.
  2. Adding new properties to existing API responses.
  3. Changing the order of properties in existing API responses.
  4. Adding new API resources or methods.
  5. Changing the length or format of opaque strings, such as resource IDs, error messages, and other human-readable strings.