> 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

### Signing requests

First of all to use Calypso Public API you’ll need to generate a new pair of API keys (public and secret keys) for your account ([How to create API keys](https://docs.calypso.money/get-started-with-calypso-ui/general/how-to-create-new-api-key)):

```
secret key example:
b823a6b9ea72408583cef9ec8d67fa52
public key example:
c529e14832b34b74972365cf7bf02430
```

API keys are used for authorization in requests to the Calypso API. After generate API keys you can start sending requests to Calypso Public API.

**All requests must contain the following headers:**

| Key          | The api key as a string.                                                        |
| ------------ | ------------------------------------------------------------------------------- |
| Sign         | The HEX-encoded signature (see below).                                          |
| Content-Type | All request bodies should have content type application/json and be valid JSON. |

**Sign** — POST data (in the same format in which you want to send) encrypted with the method HMAC-SHA512 using secret key and the result object is converted to a HEX string.

The body is the request body string (in all cases this is JSON stringified request params object).

All the requests should also include the obligatory POST parameter `timestamp` with current unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past and not greater than 3 minutes in the future.

To create the sign:

1. Build the body of the request with correct `timestamp`
2. Encrypt the request body with method HMAC-SHA512 using the body as a message and the secret key as a key.
3. Convert bytes to string of hexadecimal digits.

Examples of sign building:

* Javascript

  JSX

  ```jsx
  const crypto = require("crypto-js");

  signature = function (body, secretKey) {
          return crypto.HmacSHA512(body, secretKey).toString(crypto.enc.hex);
      };
  ```
* Python

  Python

  ```python
  import hmac
  import hashlib

  def signature(body, secret_key):
      return hmac.new(secret_key.encode(), body.encode(), hashlib.sha512).hexdigest()
  ```

Example of api keys, body and correct sign for request:

Python

```python
api_key = 'c529e14832b34b74972365cf7bf02430'
secret_key = 'b823a6b9ea72408583cef9ec8d67fa52'

data = '{"timestamp":1}'
sign = 'b16e9d45f49f2069becbc4f108b237bee588cfc353fe9501df103e692acbc68d482a10d34c12bea22fedde7e28e1b8e57a6a0a373b0e9a27c5257bd8b36e13b9'
```

Examples of timestamp building:

* Javascript

JavaScript

```javascript
var timestamp = new Date().getTime();
```

* Python

Python

```python
import time

timestamp = round(time.time() * 1000)
```

## **Handling Unknown Parameters in API**

#### **Backward Compatibility Principle**

Our API follows the **"Robustness Principle".**

#### **API Client Requirements**

API client applications and integrations **MUST** ignore any unknown or unsupported parameters received in API responses.

#### **Prohibited Actions**

❌ **NOT ALLOWED:**

* Throwing exceptions/errors when unknown parameters are detected
* Stopping response processing due to new fields
* Validating responses against strict schemas that don't allow extensions
* Breaking functionality because of additional data

#### **Why This Is Important?**

**Ensuring Backward Compatibility:**

* API can add new features without breaking changes
* Old clients continue working with new API versions
* Gradual feature rollout without forced client updates

**Business Benefits:**

* **Zero downtime updates** - API updates don't require synchronous client updates
* **Development flexibility** - ability to A/B test new features
* **Gradual migration** - clients can update at their own pace

#### **Handling Incoming Requests**

**Note:** This rule applies specifically to **API responses**. For incoming requests to our API, clients should only send documented parameters, while our server will reject unknown parameters in requests according to our validation rules.


---

# 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:

```
GET https://docs.calypso.money/get-started-with-calypso-api/api-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.