Skip to content
QuantLabTickDirect

DocsProtocol

Authentication (JWT)

How to create the JWT you send in Authenticate.

The Tick server identifies you with a JWT signed with your ggguilds API key. The JWT is the standard JWT described in ggguilds' "Using API keys", with nonce added.

Claims

FieldValue
Header algEdDSA (Ed25519)
issKey ID (ggg_...)
audfreqrelay (a fixed value)
iatWhen the token was created (UNIX time in seconds)
expExpiry (UNIX time in seconds). Within 5 minutes of iat
nonceThe cookie from Challenge (16 bytes) as URL-safe Base64 without padding (22 characters)
  • Create a new JWT every time you send Authenticate, because the cookie changes each time.
  • A clock difference of up to ±60 seconds from the Tick server is allowed. Keep the client's clock in sync with NTP or similar.
  • Send the JWT in compact form (ASCII), at most 1,024 bytes.

Python example

This uses PyJWT.

# pip install "pyjwt[crypto]"
import base64, time, jwt

with open("ggguilds-api-key.pem", "rb") as f:
    private_key = f.read()
now = int(time.time())
token = jwt.encode(
    {
        "iss": key_id,  # Key ID (ggg_...)
        "aud": "freqrelay",
        "iat": now,
        "exp": now + 300,
        "nonce": base64.urlsafe_b64encode(cookie).rstrip(b"=").decode(),  # Cookie from Challenge
    },
    private_key,
    algorithm="EdDSA",
)

JavaScript example

This uses jose.

// npm install jose
import { SignJWT, importPKCS8 } from "jose"

const privateKey = await importPKCS8(pem, "EdDSA")
const token = await new SignJWT({ nonce: Buffer.from(cookie).toString("base64url") })
  .setProtectedHeader({ alg: "EdDSA" })
  .setIssuer(keyId) // Key ID (ggg_...)
  .setAudience("freqrelay")
  .setIssuedAt()
  .setExpirationTime("5m")
  .sign(privateKey)

When authentication is rejected

The result in AuthenticateAck tells you why. The common ones are below. All values are in Result codes.

resultWhat to check
InvalidSignatureWhether the key ID and the private key belong together
TokenExpiredWhether the client's clock is correct, and whether exp − iat is within 5 minutes
UnknownKeyIf you just issued the key, wait about a minute and retry
IpLimitReachedStopping a connection on another IP address frees a slot

Why the source address is checked

Getting a Challenge in reply to Hello and returning its cookie in the JWT confirms that the source address is genuine. The cookie is derived from the source address and a time window, so a request with a spoofed source address cannot authenticate.

For the same reason, Hello carries 32 bytes of padding (all zeros). This makes Hello larger than Challenge, so that a request with a spoofed source address cannot make the server send a larger reply to a third party. The Tick server does not reply to a Hello without the padding.