FiniAC Documentation

Appearance

API Version 3 ​

INFO

This is the documentation for the FiniAC Public API version 3. This version is the latest and is recommended for all new integrations.

Introduction ​

The FiniAC Public API is a RESTful API that allows you to interact with the Fini Anti-Cheat system. This API is designed to be simple and easy to use, with a focus on speed and reliability. The API is versioned to allow for changes and improvements over time, while maintaining backwards compatibility.

Getting Started ​

To get started with the FiniAC Public API, you will need to register for an API key. Once you have your API key, you can start making requests to the API.

Registering for an API Key ​

Currently to register for an API Key for the FiniAC Public API, you will need to contact us directly. We are working on a self-service registration system, but for now, please contact us to get started.

API Key Permissions ​

API keys are granted permissions based on the needs of the application using the API. When a permission for a specific endpoint is required, it will be listed in the endpoint's documentation. Calling the endpoint without the required permission will result in a 403 response and the name of the missing permission in the response message field.

Authentication ​

To authenticate with the API, you will need to include an access key and a secret key. The secret key will only be displayed once when the API token is refreshed.

API authentication examples:

http
GET /api/v3/keys/verify
Host: fini.dev
X-Fini-AccessKey: YOUR_ACCESS_KEY
X-Fini-SecretKey: YOUR_SECRET_KEY
bash
curl \
-X GET "https://fini.dev/api/v3/keys/verify" \
-H "X-Fini-AccessKey: YOUR_ACCESS_KEY" \
-H "X-Fini-SecretKey: YOUR_SECRET_KEY"
js
fetch("https://fini.dev/api/v3/keys/verify", {
  method: "GET",
  headers: {
    "X-Fini-AccessKey": "YOUR_ACCESS_KEY",
    "X-Fini-SecretKey": "YOUR_SECRET_KEY"
  }
})
js
axios.get("https://fini.dev/api/v3/keys/verify", {
  headers: {
    "X-Fini-AccessKey": "YOUR_ACCESS_KEY",
    "X-Fini-SecretKey": "YOUR_SECRET_KEY"
  }
})

Endpoints ​

API Keys ​

GET /api/v3/keys/verify ​

Purpose: The API key verification endpoint is used to verify that the API key is valid and has not been revoked.

Authentication: Requires a valid API Key.

Permissions

List of permissions that can be granted to an API key can be found here

ts
{
  success: boolean;
  info: {
    id: number;
    comment: string; // Optional comment [From FiniAC Staff]
    permissions: string; // Comma-separated list of permissions
    created_time: number; // Unix timestamp
    last_used: number; // Unix timestamp
    user: number; // User ID
    server_name: number; // Server name
    server_id: number; // Server ID
  }
}

Apollo ​

POST /api/v3/apollo/exec ​

Purpose: Executes a provided script within a defined server environment. Returns either the script's execution output or a token for retrieving the output later.

Authentication: Requires an API Key with the APOLLO.EXEC permission.

Input Parameters (Body)

json
{
  "script": "<string max 32kb>", // The script to execute
  "ip_addr": "<string formatted x.x.x.x>" // The IP address of the server to execute the script in
}

Responses

json
{
  "success": true,
  "message": "<string>", // Optional message
  "token": "<string>" // Used to retrieve the output later
}
json
{
  "success": false,
  "code": "<int>", // Error code
  "message": "<string>" // Optional message
}

GET /api/v3/apollo/return ​

Purpose: Retrieves the results of a previously executed script (where a token was provided).

Authentication: Requires an API Key with the APOLLO.EXEC permission.

Query Parameters

Responses

json
{
  "success": true,
  "value": "<string>" // The output of the script
}
json
{
  "success": false,
  "code": "<int>", // Error code
  "message": "<string>" // Optional message
}

Users ​

Purpose: Searches for users based on provided parameters like username, IP address, or Discord ID.

Authentication: Requires a valid API key with the USERS.SEARCH permission

Query Parameters

  • username (string, optional): The username to search for.
  • ipaddress (string, optional): The IP address to search for.
  • discord (string, optional): The Discord ID to search for.

Responses

json
{
  "success": true,
  "code": 200,
  "users": [
    {
      "id": 123,
      "username": "johndoe",
      "ip_addr": "127.0.0.1",
      "last_activity": 1679179153, // Example timestamp
      "created": 1676687521, // Example timestamp
      "discord_id": "123456789012345678",
      "servers": [
        {
          "id": 1,
          "name": "My Cool Server",
          "max_ips": 20,
          "last_connect": 1679175007, // Example timestamp
          "owner": 123 // User ID of owner
        }
        // ... other servers
      ]
    }
    // ... other matching users
  ]
}
json
// Emitted if no search parameters (username, ipaddress, or discord) are provided.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

Subscriptions ​

GET /api/v3/subscriptions/:subId/configs(?/:confId) ​

Purpose: This endpoint retrieves subscription configuration details.

Authentication: Requires a valid API key with the SUBSCRIPTIONS.CONFIGS permission.

URL Parameters

  • subId (number, required): Unique ID of the subscription.
  • confId (number, optional): Unique ID of a specific configuration to retrieve. If omitted, all configurations for the subscription are returned.

Responses

json
{
  "success": true,
  "code": 200,
  "configs": [
    {
      "id": "<number>",
      "subscription_id": "<number>",
      "value": "<array,string,number,object>",
      "name": "<string>",
      "name_friendly": "<string, readable>",
      "category": "<string>",
      "weight": "<number, float>",
      "type": "<string>",
      "default_value": "<array,string,number,object>",
      "required_feature_id": "<number>"
    }
    // More config objects if applicable...
  ]
}
json
// 400: Missing required parameters.
// 404: Subscription or specified configuration not found.
{
  "success": false,
  "code": "<int>", // Error code
  "message": "<string>" // Optional message
}

PUT /api/v3/subscriptions/:subId/configs/:confId ​

Purpose: This endpoint is designed to modify the value of an existing configuration within a specified subscription.

Authentication Requires a valid API key with the SUBSCRIPTIONS.CONFIGS permission.

Inputs

Request Body:

json
{
  "value": "<array,string,number,object>"
}

URL Parameters:

  • subId (string, required in URL): The unique identifier of the subscription that the configuration belongs to.
  • confId (string, required in URL): The unique identifier of the specific configuration you want to update.

Responses

json
{
  "success": true,
  "code": 200
}
json
// 400: Missing required parameters.
// 404: Subscription or specified configuration not found.
// 403: API key lacks necessary permissions.
{
  "success": false,
  "code": "<int>", // Error code
  "message": "<string>" // Optional message
}

Servers ​

Purpose: Searches for servers based on specified criteria (name or Discord user ID).

Authentication: Requires an API Key with the SERVERS.SEARCH permission.

Query Parameters

  • name (string, optional): The name of the server.
  • uid (number, optional): The Discord user ID associated with the server.

Responses

json
{
  "success": true,
  "code": 200,
  "servers": [
    {
      "id": 1,
      "name": "Test Server",
      "max_ips": 4,
      "owner": "John Doe",
      "users": [
        {
          /* User details */
        }
        /* (..more..) */
      ],
      "subscriptions": [
        {
          /* Subscription details */
        }
      ]
    }
    /* (..more..) */
  ]
}
json
// 400: Missing search parameters.
// 404: Servers not found with the provided criteria.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

Identities ​

POST /api/v3/identities/match ​

Purpose: This endpoint allows users to match multiple player identifiers to known player records within your system. This can be valuable for cross-referencing different player identification systems or for consolidating data.

Authentication:

This endpoint requires a valid API key with the permission BANS.MATCH.

Inputs

  • identifiers (array): A required array of player identifiers. Must be provided in the POST body. Each identifier should be an object with a type and a value property.

    Example identifiers array:

    json
    [
  { "type": "steam", "value": "76561199999999999" },
  { "type": "license", "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" },
  { "type": "ip", "value": "123.123.123.123" }
]

Limits: You may search for up to 5 identifiers in a single request.

Responses

json
{
  "success": true,
  "matches": [
    /* An array of player objects */
  ]
}
json
// 400: Missing required parameters.
// 401: Unauthorized (invalid API key).
// 403: Forbidden (lacks necessary permissions).
// 429: Rate limit exceeded.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

Bans ​

GET /api/v3/bans/:uid ​

Purpose: Searches for bans associated with a license ID (uid).

Authentication: Requires a valid API key with the BANS.CHECK permission.

Optionally requires the BANS.CHECK.GLOBAL permission to view bans global bans (server_id = 0).

Optionally requires the BANS.DATE permission to view ban timestamps.

Optionally requires the BANS.REASON permission to view ban reasons.

Optionally requires the BANS.SEVERITY permission to view ban severity.

Parameters

URL Parameters:

  • uid (number, required): The license ID to check.

Responses

json
{
  "success": true,
  "code": 200,
  "bans": [
    {
      "id": "182475",
      "uid": "cf41abbb661b9f8c9fcbe3aa36f7178102e31c1d",
      "global": true,
      "created_by": "GLaDOS",
      "server_name": "Aperture Laboratories",
      "type": "fini",
      // Optional fields
      "time_unix": "1693351512", // Requires BANS.DATE permission
      "time_iso": "2023-08-29T23:25:12+00:00", // Requires BANS.DATE permission
      "reason": "Ban by detection logging, bad log: InvalidPedHealth\n\n{detection info as json}", // Requires BANS.REASON permission
      "severity": "high" // Requires BANS.SEVERITY permission
    }
    // ... other matching bans
  ]
}
json
// 400: Missing required parameters.
// 401: Unauthorized (invalid API key).
// 403: Forbidden (lacks necessary permissions).
// 429: Rate limit exceeded.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

GET /api/v3/bans/check/discord ​

Purpose: Checks if a user is currently banned using their Discord ID. This endpoint returns truncated ban data, only containing uid and global. For more information about a ban, use the GET /api/v3/bans/:uid endpoint.

Authentication: Requires a valid API key with the BANS.CHECK permission.

Optionally requires the BANS.CHECK.GLOBAL permission to view bans global bans.

Optionally requires the BANS.DATE permission to view ban timestamps.

Optionally requires the BANS.REASON permission to view ban reasons.

Optionally requires the BANS.SEVERITY permission to view ban severity.

Input Parameters

  • discord (Required): The Discord ID to check.

Responses

json
{
  "success": true,
  "code": 200,
  "bans": [
    {
      "uid": "cf41abbb661b9f8c9fcbe3aa36f7178102e31c1d",
      "global": true
    }
    // Additional bans...
  ]
}
json
// 400: Missing required parameters.
// 401: Unauthorized (invalid API key).
// 403: Forbidden (lacks necessary permissions).
// 429: Rate limit exceeded.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

POST /api/v3/bans/:uid ​

Purpose: Add a ban to the specified license ID (uid).

Authentication: Requires a valid API key with the BANS.ADD permission.

Additionally requires BANS.ADD.GLOBAL permission to add global bans.

Parameters

URL Parameters:

  • uid (number, required): The ban ID to update.

Body Parameters:

json
{
	"reason": "string", // The reason for the ban.
	"severity": "low" | "medium" | "high", // The severity of the ban.
	"server_id": "number" // (optioal) defaults to server_id from apikey, or 0 for global ban.
}

Responses

json
{
  "success": true,
  "code": 201,
  "message": "Ban created",
  "ban_id": "number" // The ID of the ban that was created.
}
json
// 400: Missing required parameters.
// 403: Forbidden (lacks necessary permissions).

{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

PUT /api/v3/bans/:banid ​

Purpose: Update a ban with the specified ID.

Authentication: Requires a valid API key with the BANS.EDIT permission.

Additionally requires BANS.EDIT.GLOBAL permission to alter global bans.

Parameters

URL Parameters:

  • banid (number, required): The ban ID to update.

WARNING

This endpoint uses the actual ban ID, not the license ID (uid). You must query the ban ID using the GET /api/v3/bans/:uid endpoint first.

Body Parameters:

json
{
	"reason": "string", // The reason for the ban.
	"severity": "low" | "medium" | "high", // The severity of the ban.
	"unbanned": true | false, // Unbans the ban if true.
	"server_id": "number" // Changing this to 0 will make the ban global.
}

:::

Responses

json
{
  "success": true,
  "code": 200,
  "message": "Ban updated"
}
json
// 400: Missing required parameters.
// 403: Forbidden (lacks necessary permissions).
// 404: Ban not found.

{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}