Authentication
Client ID/Secret Model
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.
Security Benefits
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
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
The signature is an HMAC-SHA256 hash of the canonicalized request body, using your Client Secret as the key.
Signature Process
Canonicalize your request body to ensure consistent JSON serialization
For GET requests with no body, use an empty string
Create an HMAC-SHA256 hash of the canonical string using your Client Secret as the key
Convert the resulting hash to a hexadecimal string
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:
// 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"}Implementation Examples
pedro or gabe plz
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
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
If you encounter any issues implementing this authentication method, reach out!
Last updated