> For the complete documentation index, see [llms.txt](https://docs.orda.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orda.network/developers/authentication.md).

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


---

# 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.orda.network/developers/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.