---
updatedAt: 2026-04-03T20:06:46.000Z
agentTools:
  projectIndex: https://developers.privacy.com/llms.txt
---

# API Basics

Learn about the Privacy API.

# Authenticating

An API key is required to get started. Generate one in the [account page](https://privacy.com/account#api-key).

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

```curl
"Authorization: YOUR_API_KEY"
```

### Example

```curl
curl --request GET \
     --url 'https://api.privacy.com/v1/card?page=1&page_size=50' \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR_API_KEY'
```

## Errors

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

## `400`

|                                    |                                                                                                 |
| ---------------------------------- | ----------------------------------------------------------------------------------------------- |
| `[query]` is not a valid parameter | A parameter in the query given in the request does not match the valid queries for the endpoint |

## `401`

|                                                               |                                                          |                                  |
| :------------------------------------------------------------ | :------------------------------------------------------- | :------------------------------- |
| User has not been authenticated                               | Invalid or missing API key                               |                                  |
| API key is not active                                         | The API key used is no longer active                     |                                  |
| Could not find API key                                        | The API key provided is not associated with any user     |                                  |
| Please provide API key in Authorization header                | The 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.                                      | Please contact <api@privacy.com>                         |                                  |
| Insufficient privileges to create unlocked cards.             | Creating unlocked cards requires an additional privilege | Please contact <api@privacy.com> |

## `422`

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

## `429`

|                                            |                                                |
| ------------------------------------------ | ---------------------------------------------- |
| Rate limited, too many requests per second | User has exceeded their per second rate limit  |
| Rate limited, reached daily limit          | User has exceeded their daily rate limit       |
| Rate limited, too many keys tried          | One IP has queried too many different API keys |

## `500`

|                       |                                                  |
| --------------------- | ------------------------------------------------ |
| Internal Server Error | There was a processing error on the server-side. |

### General Notes

* Each entity is identified by its UUID 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 ISO 8601 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:

```json
{
  "data": [
    // API OBJECTS
  ],
  "page": <Integer>,
  "total_entries": <Integer>,
  "total_pages": <Integer>
}
```