# API Authentication

### Signing requests

First of all to use Calypso Public API you’ll need to contact [Technical Support](https://t.me/calypsosup) to generate a new pair of API keys (public and secret keys):

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

API keys are used for authorization in requests to the Calypso API. After receiving API keys from our Technical Support team 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.