diff --git a/app/lib/sidebar-icons.tsx b/app/lib/sidebar-icons.tsx index f87cfb6..bf3e90a 100644 --- a/app/lib/sidebar-icons.tsx +++ b/app/lib/sidebar-icons.tsx @@ -1,11 +1,12 @@ import type { ReactNode } from 'react' -import { IconExchange, IconServer, IconTopologyBus, IconWorld } from '@tabler/icons-react' +import { IconExchange, IconKey, IconServer, IconTopologyBus, IconWorld } from '@tabler/icons-react' import { GodotIcon, UnityIcon } from '@/components/brand-icons' const icons: Record = { godot: , unity: , http: , + admin: , sockets: , selfhosting: , integrations: , diff --git a/content/docs/admin/authentication.mdx b/content/docs/admin/authentication.mdx new file mode 100644 index 0000000..a8f4df0 --- /dev/null +++ b/content/docs/admin/authentication.mdx @@ -0,0 +1,24 @@ +--- +description: Learn how to authenticate your Admin API requests. +title: Authentication +--- + +## What is the Admin API? + +The Admin API is a way of programmatically managing your game data like stats and leaderboards. + +Unlike the gameplay-orientated [HTTP API](/docs/http/authentication), which authenticates requests on behalf of players, the Admin API authenticates requests using admin API keys scoped to your game. + +## Creating an admin API key + +You can create admin API keys on the [API keys page](https://dashboard.trytalo.com/api-keys) inside the Talo dashboard. When creating a key, you choose which scopes it has. Each endpoint lists the scopes it requires (for example `read:stats` or `write:stats`). + +## Making a request + +Admin API requests are authenticated with an admin API key sent in the `Authorization` header: + +``` +Authorization: Bearer ta_..... +``` + +All Admin API endpoints are served under the `/admin/v1` prefix. diff --git a/content/docs/admin/game-stat-api.mdx b/content/docs/admin/game-stat-api.mdx new file mode 100644 index 0000000..d89c597 --- /dev/null +++ b/content/docs/admin/game-stat-api.mdx @@ -0,0 +1,78 @@ +--- +description: Manage game stats via the admin API. Create stats, find them and view their metrics. +title: Game stat admin API +--- + +import { ServiceDocumentation } from '@/components/documentation/ServiceDocumentation' +import { generateServiceTOC } from '@/lib/api-docs' + +export const service = 'GameStatAdminAPI' + +export const pageToc = [ + { title: 'Overview', url: '#overview', depth: 2 }, + { title: 'Endpoints', url: '#endpoints', depth: 2 }, + ...generateServiceTOC(service), + { title: 'Types', url: '#types', depth: 2 }, + { title: 'Stat', url: '#stat', depth: 3 }, + { title: 'StatMetrics', url: '#statmetrics', depth: 3 }, +] + +## Overview + +The game stat admin API lets you create, update, delete and reset [game stats](/docs/http/game-stat-api) programmatically, as well as read stats and their metrics. This is useful for automation like creating stats ahead of a new patch or resetting player stats between competitive seasons. + +## Endpoints + + + +## Types + +### Stat + +```ts +type Stat = { + id: number + internalName: string + name: string + global: boolean + globalValue: number + metrics?: StatMetrics // see below + defaultValue: number + maxChange: number | null + minValue: number | null + maxValue: number | null + minTimeBetweenUpdates: number + createdAt: string + updatedAt: string +} +``` + +### StatMetrics + +Metrics are **optional** and only included when the `withMetrics` query parameter is set on [list](/docs/admin/game-stat-api#get-all-game-stats) and [find](/docs/admin/game-stat-api#get-an-individual-game-stat) requests. When `withMetrics` is set, the `metrics` property is included with the stat response. + +```ts +type StatMetrics = { + globalCount: number + globalValue: GlobalValueMetrics + playerValue: PlayerValueMetrics +} + +type GlobalValueMetrics = { + minValue: number + maxValue: number + medianValue: number + averageValue: number + averageChange: number +} + +type PlayerValueMetrics = { + minValue: number + maxValue: number + medianValue: number + averageValue: number +} +``` diff --git a/content/docs/admin/meta.json b/content/docs/admin/meta.json new file mode 100644 index 0000000..ee65edf --- /dev/null +++ b/content/docs/admin/meta.json @@ -0,0 +1,5 @@ +{ + "pages": ["authentication", "game-stat-api"], + "title": "Admin API reference", + "icon": "admin" +} diff --git a/content/docs/index.mdx b/content/docs/index.mdx index d3832f8..15ea45b 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -9,6 +9,7 @@ title: Talo overview + diff --git a/content/docs/meta.json b/content/docs/meta.json index 7627f58..0ca5ec7 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -1,3 +1,3 @@ { - "pages": ["index", "godot", "unity", "http", "sockets", "selfhosting", "integrations"] + "pages": ["index", "godot", "unity", "http", "admin", "sockets", "selfhosting", "integrations"] }