Authentication

Gridy APIs use a Hash-based Message Authentication Code (HMAC) with your API credentials to add an HMAC signature to the HTTP Authorization header of each API request. This security measure provides maximum protection against man-in-the-middle and session replay attacks. These requests must also be transmitted over HTTPS TLS v1.2+; HTTPS with TLS versions below 1.2 are not supported

HMAC signing provides these added security benefits:

• The API Secret Key is never transmitted, but encrypts the HMAC from the sender-side and decrypts it from the server-side.
• The HMAC signature validates that the message was not tampered with or altered in transit. Any change to the message invalidates the HMAC.
• The HMAC signature includes a nonce (one-time code) that prevents replay attacks.

Prerequisites

Provide each request with all HTTP headers required for authentication. The minimum required are:

Http Request header	Description
x-gridy-utctime	UTC Timestamp in milliseconds. It can't be more than 15 minutes off from the current Coordinated Universal Time (Greenwich Mean Time).
x-gridy-cnonce	Universally Unique Identifier (UUID v4)
x-gridy-apiuser	Your API USER ID provided at registration
Authorization	Authentication information required by the GRIDY-HMAC-SHA512 scheme. Format and details are explained below.

Example

x-gridy-utctime 1706220321585
x-gridy-cnonce 850b9185-5b9c-434c-af3d-566f22159255
x-gridy-apiuser 000000000

gridy-hmac: apiuser=000000000,signedheaders=x-gridy-utctime;x-gridy-cnonce,algorithm=gridy-hmac512,signature=d4badae2b28c63e910c3333f19e644845f240cd36e5be4c994750c3e8651cafaee62bb4471d04f8eb514a68c165479d0d5776195faa08b8953ec23c2a0f7d045

Authorization header

Syntax

Authorization: gridy-hmac: apiuser={API USER ID},signedheaders=x-gridy-utctime;x-gridy-cnonce,algorithm=gridy-hmac512,signature={SIGNATURE}

Argument	Description
GRIDY-HMAC	Authorization scheme. (required)
Credential	Your API USER ID provided at registration (required)
Signed Headers	HTTP request headers added to the signature. (required)
Signature	Hex encoded HMAC-SHA512 of Signed Headers. (required)

Credential

Your API USER ID provided at registration

Signed headers

HTTP request header names, separated by semicolons, required to sign the request. These HTTP headers must be correctly provided with the request as well.

Java Example code:

Java

    String utcTime = Long.toString( Instant.now().toEpochMilli() );
    String cNonce = UUID.randomUUID().toString();

    String signedHeaders = String.format("x-gridy-utctime: %s\nx-gridy-cnonce: %s", this.utcTime , this.cNonce);   

Signature

Hex encoded HMAC SHA-512 hash of the Signed headers.

hex_encode( HMAC_SHA512(signedHeaders, Secret) )

Java Example code below:

Java

    import java.util.UUID;
    import java.time.Instant;

    String HMAC_SHA512_ALGORITHM = "HmacSha512";

    String apiUser = "<Your Gridy API User ID>";
    String secretKey = "<Your Gridy Secret Key>";

    String utcTime = Long.toString( Instant.now().toEpochMilli() );
    String cNonce = UUID.randomUUID().toString();

    String signedHeaders = String.format("x-gridy-utctime: %s\nx-gridy-cnonce: %s", this.utcTime , this.cNonce);

    SecretKeySpec signingKey = new SecretKeySpec( secretKey.getBytes(), HMAC_SHA512_ALGORITHM );
    Mac mac = Mac.getInstance(HMAC_SHA512_ALGORITHM);
    mac.init(signingKey);

    byte[] rawHmac = mac.doFinal( signedHeaders.getBytes());
    String hmacSignature = Hex.encodeHexString(rawHmac);

Java Example Code

Java

     import javax.crypto.Mac;
     import javax.crypto.spec.SecretKeySpec;
     import java.util.UUID;
     import java.time.Instant;
     import org.apache.commons.codec.binary.Hex;

     String HMAC_SHA512_ALGORITHM = "HmacSha512";

     String apiUser = "<Your Gridy API User ID>";
     String secretKey = "<Your Gridy Secret Key>";

     String utcTime = Long.toString( Instant.now().toEpochMilli() );
     String cNonce = UUID.randomUUID().toString();

     String signedHeaders = String.format("x-gridy-utctime: %s\nx-gridy-cnonce: %s", this.utcTime , this.cNonce);

     SecretKeySpec signingKey = new SecretKeySpec( secretKey.getBytes(), HMAC_SHA512_ALGORITHM );
     Mac mac = Mac.getInstance(HMAC_SHA512_ALGORITHM);
     mac.init(signingKey);

     byte[] rawHmac = mac.doFinal( signedHeaders.getBytes());
     String hmacSignature = Hex.encodeHexString(rawHmac);

     String hmacAuthHdr = String.format( "gridy-hmac: apiuser=%s,signedheaders=x-gridy-utctime;x-gridy-cnonce,algorithm=gridy-hmac512,signature=%s", apiUser, hmacSignature );

Authorization Header

Authorization gridy-hmac: apiuser=<Your API UserID>,signedheaders=x-gridy-utctime;x-gridy-cnonce,algorithm=gridy-hmac512,signature=9f2571a0bdc0bcac09f26f340acd2f935bf5e4d5869d4089cbdff3e3d94a43d9c39ab7b995b

Troubleshooting

See list of common related API error codes below:

 

Http Status		API Status	Description	Help
400	Bad Request
		-4004	HTTP Header x-gridy-utctime missing	x-gridy-utctime header missing from HTTP headers
		-4005	HTTP Header x-gridy-utctime format error	x-gridy-utctime format error -
		-4006	HTTP Header x-gridy-cnonce missing
		-4007	HTTP Header x-gridy-cnonce format error
		-4008	HTTP Header x-gridy-apiuser missing error
		-4009	HTTP Header x-gridy-apiuser format error
		-4000	HTTP Authorization Header missing
		-4001	HTTP Authorization Header format error
		-4026	HTTP Authorization Header HMAC signature missing
		-4027	HTTP Authorization Header HMAC signature format error
		-4028	HTTP Authorization Header HMAC apiuser missing error
		-4029	HTTP Authorization Header HMAC apiuser format error
		-4030	HTTP Authorization Header HMAC algorithm missing error
		-4031	HTTP Authorization Header HMAC algorithm format error
		-4032	HTTP Authorization Header HMAC headers missing error
		-4033	HTTP Authorization Header HMAC headers format error
		-4034	HTTP Authorization Header HMAC nonce reused error
		-4035	HTTP Authorization Header HMAC timestamp reused error
		-4036	HTTP Authorization Header HMAC utctime clock drift error
		-4037	HTTP Authorization Header HMAC signature error