HMAC authentication

Every request to the 4league /v1 API is signed with HMAC-SHA256 using your key's secret. This page is the complete contract: headers, the canonical string, test vectors and common failures.

Server-to-server only. /v1 sends no CORS headers, so browsers cannot call it. Your secret must never ship in a web page or mobile app; sign on your own backend.

• Required headers
• The canonical string
• Test vectors
• Code examples
• The 401 response
• Troubleshooting

Required headers

Send all four on every request. Each header must be a single value (no commas, no repeats) of at most 200 characters.

The API only accepts requests without a body (GET and HEAD). The body hash is still part of the canonical string.

The canonical string

Six fields joined by a single line feed (\n, no trailing newline):

METHOD\nPATH\nSORTED_ENCODED_QUERY\nTIMESTAMP\nNONCE\nSHA256hex(body)

The signature is hex(HMAC_SHA256(secret, canonical)), with the canonical string encoded as UTF-8.

Rules

• METHOD: the HTTP method, upper-cased.
• PATH: the raw request path exactly as sent, starting at /v1, without the query. It is never decoded. A trailing slash counts (/v1/matches/ and /v1/matches sign differently). The only change is that the hex digits of existing percent-escapes are upper-cased (%2f becomes %2F).
• SORTED_ENCODED_QUERY, built from the part after ?:
  1. Split on & and drop empty parts.
  2. Split each part at the first =. A bare key (a) becomes a=.
  3. Percent-decode the key and the value, then re-encode both per RFC 3986: only A-Za-z0-9-._~ stay unencoded. ! ' ( ) * and + are encoded. A + is a literal plus, not a space. Hex digits are upper-case.
  4. Sort the pairs by encoded key, then by encoded value (plain code-unit order, so B sorts before a). Duplicate keys are kept.
  5. Join as key=value with &. No query gives an empty line.
• TIMESTAMP and NONCE: the same strings you send in the headers.
• SHA256hex(body): lowercase hex SHA-256 of the raw body. For an empty body it is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

The server answers 400 (not 401) for malformed percent-encoding (a % not followed by two hex digits) and for any URL longer than 2048 bytes.

Test vectors

The table below is generated from hmac-vectors.json (raw JSON), the same file the backend tests run against. Check that your implementation reproduces both the canonical string and the signature for every row.

• Signing GET and HEAD vectors are what the API accepts.
• Canonicalization only POST and PUT vectors exist to test body hashing and UTF-8 handling. The API does not accept those methods.

All vectors work offline only. Their timestamp (1760000000) is long outside the ±300 s window, so the live API rejects them. Use them to compare strings, not to call the API.

Secret for every vector: test_secret_4league_v1_vectors. Timestamp: 1760000000. 17 vectors.

GET\n
/v1/matches\n
\n
1760000000\n
nonce-001\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

GET\n
/v1/matches\n
a=1&a=2\n
1760000000\n
nonce-002\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

GET\n
/v1/matches\n
a=\n
1760000000\n
nonce-003\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

GET\n
/v1/teams\n
q=a%20b\n
1760000000\n
nonce-004\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

GET\n
/v1/teams\n
q=a%2Bb\n
1760000000\n
nonce-005\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

GET\n
/v1/teams\n
q=a%20b&q=a%20b&q=a%2Bb\n
1760000000\n
nonce-006\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

GET\n
/v1/teams\n
q=%21%2A%27%28%29\n
1760000000\n
nonce-007\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

GET\n
/v1/teams\n
q=~-._\n
1760000000\n
nonce-008\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

GET\n
/v1/teams\n
n=caf%C3%A9&q=%C8%99coal%C4%83\n
1760000000\n
nonce-009\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

GET\n
/v1/teams\n
path=a%2Fb\n
1760000000\n
nonce-010\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

GET\n
/v1/teams/a%2Fb\n
\n
1760000000\n
nonce-011\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

GET\n
/v1/matches/\n
a=1\n
1760000000\n
nonce-012\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

HEAD\n
/v1/matches\n
limit=5\n
1760000000\n
nonce-013\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

GET\n
/v1/players\n
limit=10&page=2\n
1760000000\n
nonce-014\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

GET\n
/v1/matches\n
B=0&a=1&a=3&a=~&b=2\n
1760000000\n
nonce-015\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

POST\n
/v1/matches\n
\n
1760000000\n
nonce-016\n
82574f474fed0a660c9bb9231dd8cedeeb3a821366a740254a741b2e8bce0a40

PUT\n
/v1/teams\n
id=7\n
1760000000\n
nonce-017\n
814f3910f94697d5efbc75c84b6c0deed320fbdb0c9152d26a64dc910f4c0c63

Code examples

'use strict';
// 4league /v1 request signing, Node.js (built-in crypto only).
const crypto = require('crypto');

// RFC 3986: only A-Z a-z 0-9 - . _ ~ stay literal. encodeURIComponent leaves !'()* alone, so fix those.
const encode = (s) =>
  encodeURIComponent(s).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());

// Percent-decode to UTF-8. '+' is a literal plus, never a space.
const decode = (s) => decodeURIComponent(s);

function canonicalQuery(rawQuery) {
  return rawQuery
    .split('&')
    .filter(Boolean)
    .map((part) => {
      const i = part.indexOf('=');
      const k = i < 0 ? part : part.slice(0, i);
      const v = i < 0 ? '' : part.slice(i + 1); // bare key "a" becomes "a="
      return [encode(decode(k)), encode(decode(v))];
    })
    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0))
    .map(([k, v]) => `${k}=${v}`)
    .join('&');
}

// The path is never decoded; only the hex digits of existing escapes are upper-cased.
const canonicalPath = (p) => p.replace(/%[0-9a-fA-F]{2}/g, (m) => m.toUpperCase());

function sign({ secret, method, path, query = '', timestamp, nonce, body = '' }) {
  const bodyHash = crypto.createHash('sha256').update(body, 'utf8').digest('hex');
  const canonical = [method.toUpperCase(), canonicalPath(path), canonicalQuery(query), timestamp, nonce, bodyHash].join('\n');
  const signature = crypto.createHmac('sha256', secret).update(canonical, 'utf8').digest('hex');
  return { canonical, signature };
}

module.exports = { sign, canonicalQuery };

if (require.main === module) {
  const timestamp = String(Math.floor(Date.now() / 1000)); // seconds, not milliseconds
  const nonce = crypto.randomBytes(16).toString('hex'); // new nonce on every attempt
  const { signature } = sign({ secret: process.env.FOURLEAGUE_SECRET, method: 'GET', path: '/v1/ping', timestamp, nonce });
  fetch('https://api.4league.app/v1/ping', {
    headers: {
      'X-4League-Key': process.env.FOURLEAGUE_KEY_ID,
      'X-4League-Timestamp': timestamp,
      'X-4League-Nonce': nonce,
      'X-4League-Signature': signature,
    },
  }).then(async (r) => console.log(r.status, await r.text()));
}

<?php
// 4league /v1 request signing, PHP 7.4+ (hash_hmac + rawurlencode).

// rawurlencode is RFC 3986: only A-Z a-z 0-9 - . _ ~ stay literal, '+' becomes %2B.
// rawurldecode never turns '+' into a space.
function fl_canonical_query(string $rawQuery): string
{
    $pairs = [];
    foreach (explode('&', $rawQuery) as $part) {
        if ($part === '') {
            continue;
        }
        $kv = explode('=', $part, 2);
        $k = rawurlencode(rawurldecode($kv[0]));
        $v = rawurlencode(rawurldecode($kv[1] ?? '')); // bare key "a" becomes "a="
        $pairs[] = [$k, $v];
    }
    usort($pairs, function ($a, $b) {
        return strcmp($a[0], $b[0]) ?: strcmp($a[1], $b[1]);
    });
    return implode('&', array_map(function ($p) {
        return $p[0] . '=' . $p[1];
    }, $pairs));
}

// The path is never decoded; only the hex digits of existing escapes are upper-cased.
function fl_canonical_path(string $path): string
{
    return preg_replace_callback('/%[0-9a-fA-F]{2}/', function ($m) {
        return strtoupper($m[0]);
    }, $path);
}

function fl_sign(string $secret, string $method, string $path, string $query, string $timestamp, string $nonce, string $body = ''): array
{
    $canonical = implode("\n", [
        strtoupper($method),
        fl_canonical_path($path),
        fl_canonical_query($query),
        $timestamp,
        $nonce,
        hash('sha256', $body),
    ]);
    return ['canonical' => $canonical, 'signature' => hash_hmac('sha256', $canonical, $secret)];
}

if (PHP_SAPI === 'cli' && isset($argv[0]) && realpath($argv[0]) === __FILE__) {
    $timestamp = (string) time(); // seconds
    $nonce = bin2hex(random_bytes(16)); // new nonce on every attempt
    $sig = fl_sign(getenv('FOURLEAGUE_SECRET'), 'GET', '/v1/ping', '', $timestamp, $nonce)['signature'];
    $ch = curl_init('https://api.4league.app/v1/ping');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-4League-Key: ' . getenv('FOURLEAGUE_KEY_ID'),
            'X-4League-Timestamp: ' . $timestamp,
            'X-4League-Nonce: ' . $nonce,
            'X-4League-Signature: ' . $sig,
        ],
    ]);
    echo curl_exec($ch), "\n";
}

"""4league /v1 request signing, Python 3 (hmac + hashlib + urllib)."""
import hashlib
import hmac
import os
import re
import secrets
import time
import urllib.request
from urllib.parse import quote, unquote


def encode(s):
    # safe='' encodes everything but A-Za-z0-9 _ . - ~ (RFC 3986 unreserved), including / ! ' ( ) *
    return quote(s, safe='')


def canonical_query(raw_query):
    pairs = []
    for part in raw_query.split('&'):
        if not part:
            continue
        k, _, v = part.partition('=')  # bare key "a" becomes "a="
        # unquote (not unquote_plus): '+' is a literal plus, never a space
        pairs.append((encode(unquote(k)), encode(unquote(v))))
    pairs.sort()  # by encoded key, then encoded value; duplicates are kept
    return '&'.join(f'{k}={v}' for k, v in pairs)


def canonical_path(path):
    # never decoded; only the hex digits of existing escapes are upper-cased
    return re.sub(r'%[0-9a-fA-F]{2}', lambda m: m.group(0).upper(), path)


def sign(secret, method, path, query, timestamp, nonce, body=''):
    body_hash = hashlib.sha256(body.encode('utf-8')).hexdigest()
    canonical = '\n'.join([method.upper(), canonical_path(path), canonical_query(query), timestamp, nonce, body_hash])
    signature = hmac.new(secret.encode('utf-8'), canonical.encode('utf-8'), hashlib.sha256).hexdigest()
    return canonical, signature


if __name__ == '__main__':
    timestamp = str(int(time.time()))  # seconds
    nonce = secrets.token_hex(16)  # new nonce on every attempt
    _, signature = sign(os.environ['FOURLEAGUE_SECRET'], 'GET', '/v1/ping', '', timestamp, nonce)
    req = urllib.request.Request('https://api.4league.app/v1/ping', headers={
        'X-4League-Key': os.environ['FOURLEAGUE_KEY_ID'],
        'X-4League-Timestamp': timestamp,
        'X-4League-Nonce': nonce,
        'X-4League-Signature': signature,
    })
    with urllib.request.urlopen(req) as r:
        print(r.status, r.read().decode())

#!/usr/bin/env bash
# 4league /v1 ping with curl + openssl. Needs FOURLEAGUE_KEY_ID and FOURLEAGUE_SECRET.
# Only valid for requests without a query string; for anything else use a helper that
# builds the canonical query (Node, PHP or Python tabs).
set -euo pipefail

TS=$(date +%s)                      # seconds
NONCE=$(openssl rand -hex 16)       # new nonce on every attempt
EMPTY_SHA=$(printf '' | openssl dgst -sha256 -hex | awk '{print $NF}')
CANONICAL=$(printf 'GET\n/v1/ping\n\n%s\n%s\n%s' "$TS" "$NONCE" "$EMPTY_SHA")
SIG=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$FOURLEAGUE_SECRET" -hex | awk '{print $NF}')

curl -sS https://api.4league.app/v1/ping \
  -H "X-4League-Key: $FOURLEAGUE_KEY_ID" \
  -H "X-4League-Timestamp: $TS" \
  -H "X-4League-Nonce: $NONCE" \
  -H "X-4League-Signature: $SIG"

HTTP/1.1 200 OK
{
  "data": {
    "apiVersion": 1,
    "serverTime": "2026-10-13T07:22:37.759Z",
    "keyId": "key1",
    "resourceType": "organization",
    "resourceId": "64b000000000000000000001",
    "scopes": [
      "competitions:read",
      "matches:read",
      "standings:read",
      "teams:read",
      "players:read",
      "matchStatistics:read",
      "organizations:read"
    ]
  }
}

The 401 response

Authentication failures return HTTP 401 with the same message. Do not branch on anything except the status and error.code.

malformedHeader Subject to change

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid credentials",
    "reason": "malformedHeader"
  }
}

The reason field is returned today only for malformed or missing headers. The owner is still deciding whether all 401 bodies should be identical; do not rely on reason.

otherFailures

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid credentials"
  }
}

Unknown or revoked key, stale timestamp, bad signature, replayed nonce: no reason field.

Troubleshooting unauthorized

The API deliberately does not say which check failed. Work through these in order:

• Clock skew. Your clock must be within 300 seconds of real time. Sync with NTP and log the timestamp you send.
• Milliseconds instead of seconds. Date.now() in JavaScript and System.currentTimeMillis() in Java return milliseconds. Divide by 1000 and floor. A 13-digit timestamp is wrong.
• Reused nonce. A nonce is accepted once per key, and only after the signature validated. Generate a fresh random nonce for every attempt, including retries after a 403 or 429.
• Encoding mismatch. Compare your canonical string with the vectors above: + must become %2B, spaces %20, !'()* must be encoded, hex upper-case, pairs sorted by encoded key then value.
• Path differs from what you sent. Sign the exact path you request, including a trailing slash, and do not decode percent-escapes in it.
• Signature format. It must be 64 hex characters. Base64 or a truncated digest returns the malformedHeader variant.
• Wrong secret or revoked key. Check the key id and that the secret belongs to it.