> For the complete documentation index, see [llms.txt](https://docs.calypso.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.calypso.money/get-started-with-calypso-api/api-authentication.md).
# API Authentication
## **Overview**
Calypso Public API uses API keys and request signatures for authentication.
To send API requests, create a public key and a secret key in the Calypso UI. The public key is sent in the `Key` header. The secret key is used only on the merchant side to create the request signature and must not be shared.
{% content-ref url="/pages/p8G4kgobaCIYQOVDIYEw" %}
[How to create new API key](/get-started-with-calypso-ui/general/how-to-create-new-api-key.md)
{% endcontent-ref %}
## **Required headers**
| Header | Required | Description |
| ------------ | -------- | ------------------------------------------------------------ |
| Key | Yes | Public API key. |
| Sign | Yes | HEX-encoded HMAC-SHA512 signature of the exact request body. |
| Content-Type | Yes | Must be `application/json`. |
## **Request body requirements**
Every API request body must be valid JSON and must include `timestamp`.
| Field | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| timestamp | number | Yes | Current Unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past or greater than 3 minutes in the future. |
Account-scoped methods also include `account`, and methods with business parameters include `payload`. See each API method for its exact request body.
## **How to create a signature**
{% stepper %}
{% step %}
Build the final JSON request body, including the current `timestamp`.
{% endstep %}
{% step %}
Convert the request body to the exact string that will be sent to Calypso.
{% endstep %}
{% step %}
Create an HMAC-SHA512 hash using the request body string as the message and the secret key as the key.
{% endstep %}
{% step %}
Convert the hash bytes to a lowercase hexadecimal string and send it in the `Sign` header.
{% endstep %}
{% endstepper %}
## **Signature examples**
### JavaScript
```javascript
const crypto = require("crypto-js");
function signature(body, secretKey) {
return crypto.HmacSHA512(body, secretKey).toString(crypto.enc.Hex);
}
```
### Python
```python
import hashlib
import hmac
def signature(body, secret_key):
return hmac.new(
secret_key.encode(),
body.encode(),
hashlib.sha512
).hexdigest()
```
## **Timestamp examples**
### JavaScript
```javascript
const timestamp = Date.now();
```
### Python
```python
import time
timestamp = round(time.time() * 1000)
```
## **Complete signing example**
```python
api_key = "c529e14832b34b74972365cf7bf02430"
secret_key = "b823a6b9ea72408583cef9ec8d67fa52"
body = '{"timestamp":1}'
sign = "b16e9d45f49f2069becbc4f108b237bee588cfc353fe9501df103e692acbc68d482a10d34c12bea22fedde7e28e1b8e57a6a0a373b0e9a27c5257bd8b36e13b9"
```
## **Handling unknown response fields**
Calypso API may add new fields to responses without breaking existing integrations.
| Requirement | Description |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Ignore unknown response fields | API clients must continue processing a response even if it contains fields that are not used by the integration. |
| Do not use strict response schemas | Response parsing must allow additional fields. |
| Send only documented request fields | Unknown request fields can be rejected by API validation. |
## **Related docs**
| Document | Link |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| Errors | [Errors](https://docs.calypso.money/get-started-with-calypso-api/errors) |
| Webhook signature check | [Sign check](https://docs.calypso.money/get-started-with-calypso-api/webhook-subscriptions/sign-check) |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.calypso.money/get-started-with-calypso-api/api-authentication.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.