Getting Started

This guide will help you get up and running with the ESFA Backend API quickly. Follow these steps to make your first API call.

Prerequisites

Before you begin, ensure you have:

API Credentials: Your apiKey and secretKey provided by your administrator
Development Environment: A tool to make HTTP requests (curl, Postman, or your preferred HTTP client)
Game Match Data: Valid gameCode and matchId for testing

Step 1: Obtain a Bearer Token

All ESFA Backend API endpoints require authentication. You'll need to obtain a Bearer token from the Authentication Service first.

Request Authentication Token

Make a POST request to the Authentication Service:

Endpoint: https://auth.your-service.tld/v1/oauth/token/machine

Headers:

Content-Type: application/json

Request Body:

{
  "apiKey": "YOUR_API_KEY",
  "secretKey": "YOUR_SECRET_KEY"
}

Example with curl

curl -X POST https://auth.your-service.tld/v1/oauth/token/machine \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "secretKey": "YOUR_SECRET_KEY"
  }'

Expected Response

{
  "data": {
    "token": "eyJhbGciOi...<snip>...",
    "expires": "2025-09-05T13:31:23.174Z"
  }
}

Step 2: Make Your First API Call

Now you can use the Bearer token to call ESFA Backend API endpoints.

Get Match Information

Let's retrieve information about a game match:

Endpoint: GET /api/v1/games/{gameCode}/matches/{matchId}

Headers:

Authorization: Bearer YOUR_TOKEN_HERE

Example with curl

curl -H "Authorization: Bearer eyJhbGciOi...<snip>..." \
  https://api.your-service.tld/api/v1/games/TTT/matches/a3c6e5f2-1a2b-4c5d-8e9f-0123456789ab

Expected Response

{
  "matchId": "a3c6e5f2-1a2b-4c5d-8e9f-0123456789ab",
  "gameCode": "TTT",
  "players": [
    {
      "id": "p1",
      "name": "Alice",
      "status": "Active",
      "imgAvatarUrl": "https://api.dicebear.com/9.x/adventurer/svg?seed=Alice"
    },
    {
      "id": "p2",
      "name": "Bob",
      "status": "Pending",
      "imgAvatarUrl": "https://api.dicebear.com/9.x/adventurer/svg?seed=Bob"
    }
  ]
}

Step 3: Submit Match Results

When a match is complete, you can submit the final results:

Endpoint: POST /api/v1/games/{gameCode}/matches/{matchId}/finish

Headers:

Authorization: Bearer YOUR_TOKEN_HERE
Content-Type: application/json

Request Body:

{
  "results": [
    {
      "playerId": "p1",
      "place": 1,
      "score": 1200
    },
    {
      "playerId": "p2", 
      "place": 2,
      "score": 900
    }
  ]
}

Example with curl

curl -X POST \
  -H "Authorization: Bearer eyJhbGciOi...<snip>..." \
  -H "Content-Type: application/json" \
  -d '{
    "results": [
      {"playerId": "p1", "place": 1, "score": 1200},
      {"playerId": "p2", "place": 2, "score": 900}
    ]
  }' \
  https://api.your-service.tld/api/v1/games/TTT/matches/a3c6e5f2-1a2b-4c5d-8e9f-0123456789ab/finish

Expected Response

HTTP/1.1 204 No Content

A 204 No Content response indicates the results were successfully processed.

Complete Workflow Script

Here's a complete bash script that demonstrates the full workflow:

#!/bin/bash

# Configuration
AUTH_SERVICE="https://auth.your-service.tld"
API_SERVICE="https://api.your-service.tld"
API_KEY="YOUR_API_KEY"
SECRET_KEY="YOUR_SECRET_KEY"
GAME_CODE="TTT"
MATCH_ID="a3c6e5f2-1a2b-4c5d-8e9f-0123456789ab"

# Step 1: Get authentication token
echo "Getting authentication token..."
TOKEN=$(curl -s -X POST $AUTH_SERVICE/v1/oauth/token/machine \
  -H "Content-Type: application/json" \
  -d "{\"apiKey\":\"$API_KEY\",\"secretKey\":\"$SECRET_KEY\"}" \
  | jq -r '.data.token')

if [ "$TOKEN" = "null" ] || [ -z "$TOKEN" ]; then
  echo "Failed to obtain token"
  exit 1
fi

echo "Token obtained: ${TOKEN:0:20}..."

# Step 2: Get match information
echo "Getting match information..."
curl -H "Authorization: Bearer $TOKEN" \
  $API_SERVICE/api/v1/games/$GAME_CODE/matches/$MATCH_ID

# Step 3: Submit match results
echo -e "\n\nSubmitting match results..."
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "results": [
      {"playerId": "p1", "place": 1, "score": 1200},
      {"playerId": "p2", "place": 2, "score": 900}
    ]
  }' \
  $API_SERVICE/api/v1/games/$GAME_CODE/matches/$MATCH_ID/finish

echo -e "\n\nWorkflow completed!"

Common Issues and Solutions

Token Expired (401 Unauthorized)

Problem: You receive a 401 Unauthorized response from the Backend API.

Solution: Your token may have expired. Repeat Step 1 to obtain a fresh token.

Invalid Credentials (401 from Auth Service)

Problem: The Authentication Service returns 401 Unauthorized.

Solution: Verify your apiKey and secretKey are correct.

Match Not Found (404)

Problem: You receive a 404 Not Found when calling match endpoints.

Solution: Verify the gameCode and matchId are valid and exist in the system.

Next Steps

Now that you've made your first API calls:

Explore Endpoints: Learn about all available API endpoints
Handle Errors: Understand error handling patterns
View Examples: Check out more code examples
Read Schemas: Review detailed schema documentation

Need Help?

Troubleshooting: Check our troubleshooting guide
API Reference: Browse the complete API documentation

05 September 2025