> For the complete documentation index, see [llms.txt](https://k4k3ru.gitbook.io/k4k3ru-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k4k3ru.gitbook.io/k4k3ru-docs/api/authentication.md). # API Request Authentication K4K3RU authenticates protected JSON-RPC methods with an API credential signature. Sign every protected request with the secret key returned when you create the API credential. ## Prerequisites Create an API credential and retain these values: * `apiKey`: Public credential identifier sent with each request. * `secretKey`: Signing key encoded as unpadded Base64 URL. * `signatureAlgorithm`: Either `hmac-sha256` or `ed25519`. The secret key is returned only when the credential is created. Store it in a secret manager, never send it to K4K3RU, and never include it in source code or logs. See [Create an API Credential with an Email OTP](/k4k3ru-docs/api/crm/create-api-credential-with-email-otp.md) to create a credential. ## Auth Object Protected methods require an `auth` object in the common [JSON-RPC request envelope](/k4k3ru-docs/api/json-rpc.md#request-envelope). | Field | Type | Required | Description | | ----------- | ------ | -------- | --------------------------------------------------- | | `apiKey` | string | Yes | Public API credential identifier. | | `timestamp` | number | Yes | Current Unix timestamp in seconds. | | `nonce` | string | Yes | Non-empty, unique value generated for this request. | | `signature` | string | Yes | Signature bytes encoded as unpadded Base64 URL. | Do not include the `id` or `auth` object in the signed payload. ## Build the Signature Payload Build the payload from the RPC method, timestamp, nonce, and canonical `params`. Join the four values with a single line-feed byte (`\n`) and do not add a trailing line feed: ``` \n\n\n ``` For example, a request with these values: * Method: `PaymentOnchain.CreateIntent` * Timestamp: `1786521600` * Nonce: `example-nonce-1` * Params: `{"productName":"usdc-base-mainnet-1"}` produces this UTF-8 payload: ``` PaymentOnchain.CreateIntent 1786521600 example-nonce-1 {"productName":"usdc-base-mainnet-1"} ``` The timestamp and nonce in this example are illustrative. Generate current, unique values for every real request. ### Canonicalize Params K4K3RU canonicalizes the raw `params` JSON before verifying the signature. Your signer must produce the same canonical representation: * Sort object keys in ascending lexicographical order at every nesting level. * Preserve array element order. * Remove insignificant spaces and line breaks. * Encode strings as JSON strings. * Preserve valid JSON number text. * Represent an omitted or empty raw `params` value as `null` when building a payload. The JSON sent in the request may contain formatting whitespace because the verifier canonicalizes it independently. Signing canonical JSON avoids depending on request formatting. ## Sign the Payload First decode `secretKey` using unpadded Base64 URL decoding. Then apply the algorithm selected when the credential was created. ### HMAC-SHA256 Compute HMAC-SHA256 over the UTF-8 payload using the decoded secret key. Encode the resulting 32 signature bytes with unpadded Base64 URL encoding. ### Ed25519 Use the decoded 64-byte Ed25519 private key to sign the UTF-8 payload. Encode the resulting 64 signature bytes with unpadded Base64 URL encoding. The `signature` field does not accept hexadecimal text, padded standard Base64, or the original secret key. ## Language Examples Choose the language used by your bot, agent tool, or application: * [Sign a Request with Go](/k4k3ru-docs/api/authentication/sign-request-with-go.md) * [Sign a Request with Python](/k4k3ru-docs/api/authentication/sign-request-with-python.md) * [Sign a Request with TypeScript](/k4k3ru-docs/api/authentication/sign-request-with-typescript.md) * [Sign a Request with Rust](/k4k3ru-docs/api/authentication/sign-request-with-rust.md) Each example builds the same type of signed JSON-RPC request and supports both credential algorithms. ## Freshness and Replay Protection K4K3RU applies these checks to every authenticated request: * `timestamp` must use Unix seconds and cannot be in the future. * A request timestamp is accepted for up to 60 seconds. * `nonce` must be non-empty and must not be reused. * Used nonces remain protected against replay for five minutes. * The signature must match the API credential's configured algorithm and key. Generate the timestamp immediately before signing. Do not retry a request with the same nonce; generate a new timestamp, nonce, payload, and signature for each attempt. ## Authentication Failures If authentication fails, check the following: * The API key belongs to the secret key used for signing. * The request uses the credential's configured signing algorithm. * The signed method and canonical params exactly match the transmitted request. * The timestamp is current Unix time in seconds, not milliseconds. * The nonce has not been used before. * The signature uses unpadded Base64 URL encoding. Never log the secret key or decoded private key while troubleshooting. --- # 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, and the optional `goal` query parameter: ``` GET https://k4k3ru.gitbook.io/k4k3ru-docs/api/authentication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.