# Authentication

#### Client ID/Secret Model <a href="#client-idsecret-model" id="client-idsecret-model"></a>

All API requests require proper signing with your Client Secret. The Client ID alone cannot be used to access the API.

* **Client ID:** Your public project identifier
* **Client Secret:** Your private signing key (must be kept secure)

**Important Security Note**: Knowing just your Client ID is not enough to access the API. All requests must be signed with your Client Secret.

{% hint style="info" %}
Obtain Keys [Here](https://app.orda.network/)
{% endhint %}

#### Security Benefits <a href="#security-benefits" id="security-benefits"></a>

This authentication model offers several security advantages:

* **Two-factor authentication**: Access requires both the Client ID and a valid signature
* **No secret transmission**: Your Client Secret is never sent to our servers
* **Request integrity**: The signature ensures requests haven't been tampered with
* **Reduced risk**: Even if your Client ID is exposed, attackers can't make API calls without the secret
* **Non-repudiation**: Signed requests provide a strong audit trail

#### Authentication Headers <a href="#authentication-headers" id="authentication-headers"></a>

All API requests to orda must include these headers:

| Header         | Description                                           |
| -------------- | ----------------------------------------------------- |
| `x-client-id`  | Your project's client ID                              |
| `x-signature`  | HMAC-SHA256 signature derived from your client secret |
| `Content-Type` | Usually application/json for requests with a body     |

**Optional Headers**

| Header        | Description                                                                    |
| ------------- | ------------------------------------------------------------------------------ |
| `x-timestamp` | Optional timestamp (in milliseconds since epoch) for preventing replay attacks |

#### Creating a Signature <a href="#creating-a-signature" id="creating-a-signature"></a>

The signature is an HMAC-SHA256 hash of the **canonicalized** request body, using your Client Secret as the key.

**Signature Process**

1. **Canonicalize** your request body to ensure consistent JSON serialization
2. For GET requests with no body, use an empty string
3. Create an HMAC-SHA256 hash of the canonical string using your Client Secret as the key
4. Convert the resulting hash to a hexadecimal string
5. Include this hex string in the x-signature header

**Canonical JSON Serialization**

The request body is canonicalized to ensure consistent signatures regardless of JSON key ordering:

* Object keys are sorted alphabetically
* No whitespace between elements
* Consistent string escaping
* Handles nested objects and arrays recursively

**Example:**

```json
// Original JSON (key order may vary)
{"name": "John", "age": 30, "city": "New York"}

// Canonical JSON (always same output)
{"age":30,"city":"New York","name":"John"}
```

**Security Recommendations**

* **Never share your Client Secret**: Your Client Secret should be treated like a password and never shared publicly or committed to version control.
* **Store secrets securely**: Use environment variables, secret management services, or secure storage solutions to manage your Client Secret.
* **Regenerate secrets if compromised**: If you suspect your Client Secret has been compromised, regenerate it immediately through the orda Dashboard.
* **Use HTTPS**: Always make API requests over HTTPS to ensure the security of your Client ID and signature.

**Implementation Tips**

* **Canonical JSON serialization**: The canonical serialization ensures consistent signatures regardless of object key ordering or JSON library differences.
* **Empty body handling**: For requests without a body (like GET requests), use an empty string as the input to the HMAC function.
* **Character encoding**: Always use UTF-8 encoding when converting strings to bytes for HMAC calculation.
* **Error handling**: Include proper error handling to diagnose signature creation issues during development.

#### Common Issues and Troubleshooting <a href="#common-issues-and-troubleshooting" id="common-issues-and-troubleshooting"></a>

**Invalid Signature Errors**

If you receive "Invalid signature" errors:

* **Check your Client Secret**: Ensure you're using the correct Client Secret for the Client ID.
* **Verify canonical serialization**: Ensure you're using the canonical JSON serialization method shown above.
* **HTTP method**: Confirm you're using the correct HTTP method (GET, POST, PUT, DELETE).
* **String encoding**: Verify you're using UTF-8 encoding for string conversions.
* **Empty bodies**: For GET requests, ensure you're signing an empty string, not "null" or "undefined".

#### Support <a href="#support" id="support"></a>

If you encounter any issues implementing this authentication method, reach out!