Signature Generation

Description

The following is an overview of the process to create a signed request. To calculate a signature, you first need a string to sign. You then calculate a HMAC-SHA256 hash of the string to sign by using a signing key.

To sign a request with a signature, you need the SIGNATURE_SECRET which will be provided by your account manager.

Step 1: Request Method (requestMethod)

Get the HTTP request method, such as GET, PUT, HEAD, and DELETE

Step 2: Host (host), Request Path (requestPath) and Query String (queryString)

1. Host: The server’s hostname
2. Request Path: The full URL path e.g., /v1/resources
3. Query String: The URL parameters without "?". It will be an empty string if no parameters e.g., param1=value1&param2=value2

Step 3: Payload Digest Generation (payloadDigest)

If the request includes a payload 1. Encode the body using SHA256 to get calculated Payload Digest 2. Convert calculated value to Lower Case HEX format

If the request doesn’t have any payload, then the Payload Digest is empty

Step 4: Signature Algorithm (signatureAlgorithm)

You can use either HMAC SHA-256 (hmac-sha256) or SHA-512 (hmac-sha512) Default = hmac-sha256

Step 5: Signature Version (signatureVersion)

The default signature version = 1.0

Step 6: Signature Key Id (signatureKeyId)

The default signature Key Id = 2

Step 7: Signature Timestamp Creation (signatureTimestampString)

The signature timestamp should be in YYYY-MM-DD HH:mm:ss format in UTC+00:00 e.g., 2025-03-20 10:12:34

Step 8: Nonce Generation (nonce)

Create a nonce by generating a random alphanumeric string of at least 16-bytes

Step 9: Signature String Generation (signatureString)

Reconstruct the signature string (signatureString) by concatenating components with ‘:’ delimiter in the following order:

1. Request Method (requestMethod) in UPPERCASE e.g., POST
2. Host (host) e.g., api.cpaas.symphony.rakuten.net
3. Request Path (requestPath) e.g., /v1/resources
4. Query String (queryString) e.g., param1=value1&param2=value2
5. Payload Digest (payloadDigest) as generated e.g., a1b2c3d4…
6. Signature Algorithm (signatureAlgorithm) e.g., hmac-sha256
7. Signature Version (signatureVersion) e.g., 1.0
8. Signature Key ID (signatureKeyId) e.g., 2
9. Timestamp (signatureTimestampString) e.g., 2025-03-11 10:00:00
10.Nonce (nonce) e.g., abc123xyz789

Final String Format:

requestMethod:host:requestPath:queryString:payloadDigest:signatureAlgorithm:signatureVersion:signatureKeyId:signatureTimestampString:nonce:

Example:

POST:api.cpaas.symphony.rakuten.net:/v1/resources:param1=value1&param2=value2:a1b2c3d4...:hmac-sha256:1.0:2:2025-03-11 10:00:00:abc123xyz789:

Important Rules:
1. Maintain exact component order
2. Use colon ":" delimiter. There is a trailing ":" at the end of the concatenated string
3. No spaces around delimiters
4. Include delimiters for empty values
5. Case-sensitive values

Step 10: Generate Signature (signature)

Generate the final signature by encoding HMAC-SHA256 (signatureString, secretKey) where secretKey = SIGNATURE_SECRET provided by Rakuten CPaaS

Step 11: Header Assignment

When making a request, put the values in the HTTP response headers

Header Name	Generated Value
host	host
x-api-signature-algorithm	signatureAlgorithm
x-api-signature-version	signatureVersion
x-api-signature-keyid	signatureKeyId
x-security-signature-timestamp	signatureTimestampString
x-api-nonce	Nonce
x-api-payload-digest	payloadDigest
x-api-signature	signature