Connect Request Signing - Challonge API Docs

For games and mobile apps, we offer an additional layer of protection to prevent fake score reporting and other attack vectors that impact distributed client-side applications.

⚠️ This feature is currently in closed beta and only available for API v2, but please reach out to us if you’re interested in trying it out.

To sign your POST & PUT match requests and protect your app from forgeries, follow the steps below. This is especially critical if you’re reporting match scores from client-side applications.

Obtain a validation secret for your app. This can be found in our Developer Portal at https://connect.challonge.com.

If you’re using the Challonge Connect Unity Asset, plug your validation secret into your configuration and you’re done! If not, you have a little more work to do — continue on to step 3.

Generate a checksum for your request. To do this, you’ll need to hash your request body using SHA-256. This is typically a 1-liner in most languages and will look similar to the Ruby code below. Make sure the request body you’re hashing is exactly what you end up sending, including any line feeds (\n) and carriage returns (\r).

Encode a JSON Web Token (JWT). https://jwt.io/ has a handy debugger that you can use to test the encoding and decoding of your signatures.

For generating the JWT, here’s what you’ll need:

Signing algorithm: HS256

HMAC secret: Your “validation secret” from step #1

The checksum from step #3

The format of your JWT’s payload should be as follows:

{
    "data": {
        "checksum": "ff72e46fbadb325f3127b4d465d144d89b42cead8c0718d050f87bb6182f0336"
    }
}

Similar to generating the checksum, encoding a JWT is typically painless. Most languages have libraries that make this simple. Here’s an example in Ruby to illustrate:

JWTs offer additional protections that we can enable for your app. We’ll document them here as we add UI support for enabling them, but in the meantime, don’t hesitate to reach out.

Add your JWT to your request as a “Signature” header.

Test. When you provide a “Signature” header, Challonge will validate it, whether or not you’ve configured your app to require request signing. If you have an app that’s live in production, we strongly recommend creating a development/test app for testing your implementation first.

If a signature you send doesn’t validate, you’ll get the following 401 response:

{
  "errors": {
    "detail": "Signature is invalid",
    "status": "401"
  }
}

Once you’re ready to require this protection and sleep better at night, you can do so by toggling this option from the Challonge Developer Portal @ https://connect.challonge.com.