​

Authentication & Signing

• OAuth2 Access Token — proves the caller’s identity
• HMAC Request Signature — proves the request has not been tampered with

Every request must pass both layers of verification. Failure of either results in 401 Unauthorized.

​

1. Obtain Access Token

POST /realms/digitalasset/protocol/openid-connect/token HTTP/1.1
Host: auth.uat.rdezlink.tech
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={api_key}
&client_secret={api_secret}

{
  "access_token": "eyJhbGciOi...",
  "token_type":   "Bearer",
  "expires_in":   300
}

• access_token can be reused within expires_in seconds. Cache it and refresh proactively 30 seconds before expiry.
• access_token must be issued by the OAuth client corresponding to X-Api-Key.

​

2. Request Signature Algorithm

string_to_sign = METHOD + PATH + TIMESTAMP + NONCE + SHA256_HEX(BODY)

signature = HEX( HMAC_SHA256( sign_secret, string_to_sign ) )

import hashlib
import hmac

def sign(method: str, path: str, ts: str, nonce: str,
         body: str, sign_secret: str) -> str:
    body_hash = hashlib.sha256(body.encode()).hexdigest()
    to_sign   = method + path + ts + nonce + body_hash
    return hmac.new(sign_secret.encode(),
                    to_sign.encode(),
                    hashlib.sha256).hexdigest()

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.MessageDigest;
import java.util.HexFormat;

public static String sign(String method, String path, String ts,
                          String nonce, byte[] body, String signSecret)
                          throws Exception {
    String bodyHash = HexFormat.of().formatHex(
        MessageDigest.getInstance("SHA-256").digest(body));
    String toSign = method + path + ts + nonce + bodyHash;
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(signSecret.getBytes(), "HmacSHA256"));
    return HexFormat.of().formatHex(mac.doFinal(toSign.getBytes()));
}

const crypto = require('crypto');

function sign(method, path, ts, nonce, body, signSecret) {
  const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
  const toSign = method + path + ts + nonce + bodyHash;
  return crypto.createHmac('sha256', signSecret)
               .update(toSign).digest('hex');
}

​

3. Request Header Specification

​

Request & Response Conventions

​

Response Envelope

{
  "code":    1,
  "message": "Success",
  "data":    { /* business data; array for list endpoints */ }
}

{
  "code":    <non-1 integer>,
  "message": "<failure reason>"
}

{
  "code": 404,
  "message": "route not found"
}

​

Error Handling

​

HTTP Status Codes & Business Codes

​

Authentication Failure Checklist

{ "code": 401, "message": "Unauthorized" }

1. Is the token valid? — Has it expired? Was it issued by the current api_key?
2. Does the signature match? — Do METHOD / PATH / BODY match the actual request?
3. Is the timestamp within the window? — Is the local clock synchronized with NTP?
4. Is the nonce unique? — Must not be reused within 5 minutes under the same api_key.

​

Rate Limiting

{
  "code":      429,
  "message":   "rate limit exceeded",
  "limit":     600,
  "window_ms": 60000
}

For higher quotas, contact your account manager. Adjustments take effect the following minute.

​

Security Recommendations