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. The following permissions are available:

APOLLO.EXEC
BANS.ADD
BANS.ADD.GLOBAL
BANS.CHECK
BANS.DATE
BANS.REASON
BANS.SEARCH
BANS.SEVERITY
DISCORD.LIST
IDENTS
LOGS
LOGS.GLOBAL
MATCH
SERVERS.SEARCH
SUBSCRIPTIONS.CONFIGS
USERS.SEARCH

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:

HTTPCURLJS FetchJS Axios

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"

fetch("https://fini.dev/api/v3/keys/verify", {
  method: "GET",
  headers: {
    "X-Fini-AccessKey": "YOUR_ACCESS_KEY",
    "X-Fini-SecretKey": "YOUR_SECRET_KEY"
  }
})

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

{
  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

Success (200)Error (400,403,404)

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

token: (string) The token generated during the execution /api/v3/apollo/exec.

Responses

Success (200)Error (400,403,404)

json

{
  "success": true,
  "value": "<string>" // The output of the script
}

json

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

Users

GET /api/v3/users/search

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

Success (200)Error (400)

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

Success (200)Error (400,404)

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

Success (200)Error (400,404,403)

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

GET `/api/v3/servers/search`

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

Success (200)Error (400,404)

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

Success (200)Error (400,401,403,429)

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/check`

Purpose: Checks if a license ID (uid) is currently banned.

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

Input Parameters

uid (Required): The license ID to check.

Responses

Success, not bannedSuccess, bannedError (400,401,403,429)

json

{
  "success": true,
  "code": 200,
  "banned": false
}

json

{
  "success": true,
  "code": 200,
  "banned": true,
  "details": {
    "time": 1647964800, // Example timestamp
    "reason": "Violation of rules"
  }
}

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, if the user is banned, it will return the ban details (subject to permissions).

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

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

Success, not bannedSuccess, bannedError (400,401,403,429)

json

{
  "success": true,
  "code": 200,
  "bans": []
}

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
    }
    // 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
}

GET `/api/v3/bans/search`

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

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

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.

Query Parameters

uid (string, required): The license ID to search for.

Responses

Success (200)Error (400,401,403,429)

json

{
  "success": true,
  "code": 200,
  "bans": [
    {
      "uid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "global": true,
      "created_by": "John Doe",
      "server_name": "Test Server",
      "type": "permanent",
      "time_unix": 1647964800, // Example timestamp
      "time_iso": "2022-03-21T00:00:00Z",
      "reason": "Violation of rules",
      "severity": 3
    }
    // ... 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/:uid`

Purpose: Searches for bans associated with a license ID (uid). (alias for /api/v3/bans/search)

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

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 ban ID to update.

Responses

Success (200)Error (400,401,403,429)

json

{
  "success": true,
  "code": 200,
  "bans": [
    {
      "uid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "global": true,
      "created_by": "John Doe",
      "server_name": "Test Server",
      "type": "permanent",
      "time_unix": 1647964800, // Example timestamp
      "time_iso": "2022-03-21T00:00:00Z",
      "reason": "Violation of rules",
      "severity": 3
    }
    // ... 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
}

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.
}

Responses

Success (201)Error (400,403)

json

{
  "success": true,
  "code": 201,
  "message": "Ban 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.ADD permission.

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

Parameters

URL Parameters:

banid (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.
	"unbanned": "true" | "false", // must be passed as a string
	"server_id": "number" // Changing this to 0 will make the ban global.
}

Responses

Success (200)Error (400,403,404)

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
}

Pages

API Version 3 ​

Introduction ​

Getting Started ​

Registering for an API Key ​

API Key Permissions ​

Authentication ​

Endpoints ​

API Keys ​

GET /api/v3/keys/verify ​

Apollo ​

POST /api/v3/apollo/exec ​

GET /api/v3/apollo/return ​

Users ​

GET /api/v3/users/search ​

Subscriptions ​

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

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

Servers ​

GET /api/v3/servers/search ​

Identities ​

POST /api/v3/identities/match ​

Bans ​

GET /api/v3/bans/check ​

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

GET /api/v3/bans/search ​

GET /api/v3/bans/:uid ​

POST /api/v3/bans/:uid ​

PUT /api/v3/bans/:banid ​

API Version 3

Introduction

Getting Started

Registering for an API Key

API Key Permissions

Authentication

Endpoints

API Keys

GET `/api/v3/keys/verify`

Apollo

POST `/api/v3/apollo/exec`

GET `/api/v3/apollo/return`

Users

GET /api/v3/users/search

Subscriptions

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

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

Servers

GET `/api/v3/servers/search`

Identities

POST `/api/v3/identities/match`

Bans

GET `/api/v3/bans/check`

GET `/api/v3/bans/check/discord`

GET `/api/v3/bans/search`

GET `/api/v3/bans/:uid`

POST `/api/v3/bans/:uid`

PUT `/api/v3/bans/:banid`