IAA BOT
IAA BOT API Security
Implement bearer authentication, HMAC SHA256 signing, timestamps, nonce replay prevention, and safe secret storage.
Required request headers#
| Header | Value |
|---|---|
| Authorization | Bearer <IAA_API_KEY> |
| X-IAA-Timestamp | Current request timestamp in the contract’s expected format. |
| X-IAA-Nonce | Unique random value used once. |
| X-IAA-Signature | HMAC SHA256 signature. |
| X-IAA-Bot-Guild-ID | Calling bot guild identity where required. |
Signature input#
The signing input is the ordered value:
METHOD
PATH_AND_QUERY
TIMESTAMP
NONCE
SHA256_BODYCompute the HMAC SHA256 with IAA_API_SIGNING_SECRET. Both sides must use identical method casing, path and query encoding, timestamp, nonce, body bytes, separators, and digest encoding.
Backend validation order#
- Validate the bearer API key.
- Reject timestamps outside the configured freshness tolerance.
- Reject a nonce that has already been used within the replay window.
- Recompute the body SHA256 and HMAC signature.
- Compare signatures with a timing-safe function.
- Validate the guild identity where the route requires it.
- Store the nonce as used only for the required replay-prevention period.