diff --git a/docs/docs/api/auth.md b/docs/docs/api/auth.md index e4a765112..7bac0da76 100644 --- a/docs/docs/api/auth.md +++ b/docs/docs/api/auth.md @@ -34,7 +34,8 @@ permissions over API Tokens, such as being able to change your password. ## Getting Tokens -[Our OAuth2 Flow](../tachi-server/infrastructure/oauth2.md) should be used to acquire API Tokens. +You should make a Tachi API Client. With that, you can use [our OAuth2 Flow](../tachi-server/infrastructure/oauth2.md), +or our [Client File Flow](../tachi-server/infrastructure/file-flow.md). ## Permissions diff --git a/docs/docs/api/routes/oauth2-clients.md b/docs/docs/api/routes/clients.md similarity index 86% rename from docs/docs/api/routes/oauth2-clients.md rename to docs/docs/api/routes/clients.md index 281d1aa3d..d2a3c23ae 100644 --- a/docs/docs/api/routes/oauth2-clients.md +++ b/docs/docs/api/routes/clients.md @@ -1,6 +1,6 @@ -# OAuth2 Client Management +# API Client Management -These endpoints relate to managing your OAuth2 clients, such as creating new ones or deleting them. +These endpoints relate to managing your Tachi API clients, such as creating new ones or deleting them. For a detailed explaination on how to use the OAuth2 flow, you can check [Using OAuth2 With Tachi](../../tachi-server/infrastructure/oauth2.md) @@ -15,7 +15,7 @@ For a detailed explaination on how to use the OAuth2 flow, you can check [Using ## Retrieve all clients you have created. -`GET /api/v1/oauth/clients` +`GET /api/v1/clients` ### Parameters @@ -31,7 +31,7 @@ None. #### Request ``` -GET /api/v1/oauth/clients +GET /api/v1/clients ``` #### Response @@ -53,7 +53,7 @@ GET /api/v1/oauth/clients ## Create a new OAuth2 Client -`POST /api/v1/oauth/clients/create` +`POST /api/v1/clients/create` ### Parameters @@ -73,7 +73,7 @@ GET /api/v1/oauth/clients #### Request ``` -POST /api/v1/oauth/clients/create +POST /api/v1/clients/create { "name": "My Client", @@ -98,7 +98,7 @@ POST /api/v1/oauth/clients/create ## Retrieve information about a client -`GET /api/v1/oauth/clients/:clientID` +`GET /api/v1/clients/:clientID` This is used to display information about this client to the user, when they are deciding on whether to authenticate it. @@ -116,7 +116,7 @@ None. #### Request ``` -GET /api/v1/oauth/clients/some_client_id +GET /api/v1/clients/some_client_id ``` #### Response @@ -134,7 +134,7 @@ GET /api/v1/oauth/clients/some_client_id ## Modify existing client -`PATCH /api/v1/oauth/clients/:clientID` +`PATCH /api/v1/clients/:clientID` ### Permissions @@ -161,7 +161,7 @@ GET /api/v1/oauth/clients/some_client_id #### Request ``` -PATCH /api/v1/oauth/clients/some_client_id +PATCH /api/v1/clients/some_client_id { "name": "new name!" @@ -182,7 +182,7 @@ PATCH /api/v1/oauth/clients/some_client_id ## Reset your client's secret. -`POST /api/v1/oauth/clients/:clientID/reset-secret` +`POST /api/v1/clients/:clientID/reset-secret` !!! warn This does **NOT** reset api keys created by this client as per OAuth2 spec. @@ -208,7 +208,7 @@ None. #### Request ``` -POST /api/v1/oauth/clients/some_client_id/reset-secret +POST /api/v1/clients/some_client_id/reset-secret ``` #### Response @@ -225,7 +225,7 @@ POST /api/v1/oauth/clients/some_client_id/reset-secret ## Delete your client. -`DELETE /api/v1/oauth/clients/:clientID` +`DELETE /api/v1/clients/:clientID` ### Permissions @@ -243,7 +243,7 @@ Empty Object. #### Request ``` -DELETE /api/v1/oauth/clients/some_client_id +DELETE /api/v1/clients/some_client_id ``` #### Response diff --git a/docs/docs/tachi-server/infrastructure/file-flow.md b/docs/docs/tachi-server/infrastructure/file-flow.md new file mode 100644 index 000000000..cf17c4eac --- /dev/null +++ b/docs/docs/tachi-server/infrastructure/file-flow.md @@ -0,0 +1,44 @@ +# Client File Flow + +While we have an [OAuth2 Flow](./oauth2.md), that requires another webserver. +What if you just want an API key to throw inside a config file? This is a +common use case. + +For this, we have the Client File Flow. This flow is entirely done on our +site, and results in the user downloading a file, or copying a string. + +## Outline + +!!! note + This documentation uses `bokutachi.xyz` as the example site. You should + replace this with the instance of Tachi you're pointing against, if it + is different. + +- You navigate the user to `https://bokutachi.xyz/client-file-flow/YOUR_CLIENT_ID`. +- They are asked if they want to create an API Key for your client. +- If they select yes, an API Key is created for your client, and depending on your client parameters, they get it. + + +## Download Format + +When you create a Tachi API Client, you can select the `File Template` parameter. This will change the format of the key given to the user. + +For example, Let's say you wanted the user to download a `.json` file with +your token. + +You could set a template of something like: + +```json +{ + "tachi-api-token": "%%TACHI_KEY%%", + "someOtherField": "foo" +} +``` + +If the `File Template` is not set, it is just output normally, without any templating. + +The first instance of `%%TACHI_KEY%%` will be replaced with the generated API key. + +The other file parameter you control is the `File Name`. If this is set, the user will be presented with a button that will download the above content. + +If it is not set, the contents of the template are shown in browser, and the user will have to copy-paste the API Key. diff --git a/docs/docs/tachi-server/infrastructure/oauth2.md b/docs/docs/tachi-server/infrastructure/oauth2.md index 483e0661b..7c30e396f 100644 --- a/docs/docs/tachi-server/infrastructure/oauth2.md +++ b/docs/docs/tachi-server/infrastructure/oauth2.md @@ -2,7 +2,7 @@ `tachi-server` has a functional implementation of OAuth2, which lets people create clients to request APIKeys from users. -This is the preferred way of handling authorisation, as it can be done without the user ever really having to deal with their API keys! +This is the preferred way of handling authorisation between web applications, as it can be done without the user ever really having to deal with their API keys! !!! note The below steps assume some familiarity with OAuth2. If you are not familiar, I find [this](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2) to be the best explaination. @@ -13,6 +13,9 @@ We use an *almost* standard OAuth2 flow, but with the added react-app caveat of In this scenario, we have two users, user A, who is making a service that integrates with Tachi, and user B, who wants to link integrate their service with their tachi profile. +!!! info + In this example we will use `bokutachi.xyz` as the Tachi site name. + - An OAuth2 client is created by user A. This client will have the following properties. @@ -24,25 +27,33 @@ This client will have the following properties. "name": "Epic Games", "author": 1, "redirectUri": "https://epicgames.example.com/tachi-auth-callback", - "requestedPermissions": ["customise_score"] + "requestedPermissions": ["customise_score"], + "apiKeyFormat": null, // These are for the Client File Flow. + "apiKeyFilename": null, // More on that later. } ``` - User B wants to link their account to this service, and must click on an auth link on Tachi. -In the `tachi-client`, this link is `/oauth/request-auth?clientID={clientID}` +In the `tachi-client`, this link is `https://bokutachi.xyz/oauth/request-auth?clientID={clientID}` EpicGames would show this link to the user, and they would click it. While on Tachi, they are presented with the option to accept linking with `clientID`, or decline it. -- If they accept, `tachi-client` will make a POST request to `/api/v1/oauth/create-code`, which will create an intermediate authorisation code. +- If they accept, `tachi-client` will make a POST request to `https://bokutachi.xyz/api/v1/oauth/create-code`, which will create an intermediate authorisation code. The user and this authorisation code are then taken to the `redirectUri` defined in the client. In our case, this means they are taken to `https://epicgames.example.com/tachi-auth-callback?code=SOME_INTERMEDIATE_TOKEN` This token **IS NOT** an API Key, but rather an intermediate value that needs to then be converted up. -EpicGames would now have to take this token and make a POST request to tachi's `/api/v1/oauth/token`, with their client secret and the intermediate token. +EpicGames would now have to take this token and make a POST request to `https://bokutachi.xyz/api/v1/oauth/token`, with their client secret and the intermediate token. -This POST request will then return the API Key EpicGames wants! The user can then be redirected by EpicGames to wherever they want. \ No newline at end of file +This POST request will then return the API Key EpicGames wants! The user can then be redirected by EpicGames to wherever they want. + +## The application I want to integrate isn't a web app! + +That's fine. Infact, it's very common for us to integrate with applications +that just want an API token inside a JSON file. For that, we have the +[Client File Flow](./file-flow.md) \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index cca6f02b2..ba5d66a96 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -4,138 +4,139 @@ site_author: zkldi site_url: https://tachi.rtfd.io theme: - name: material - features: - - navigation.instant - - navigation.tabs - palette: - - scheme: slate - primary: deep purple - accent: deep purple - toggle: - icon: material/weather-sunny - name: Switch to light mode - - scheme: default - primary: deep purple - accent: deep purple - toggle: - icon: material/weather-night - name: Switch to dark mode + name: material + features: + - navigation.instant + - navigation.tabs + palette: + - scheme: slate + primary: deep purple + accent: deep purple + toggle: + icon: material/weather-sunny + name: Switch to light mode + - scheme: default + primary: deep purple + accent: deep purple + toggle: + icon: material/weather-night + name: Switch to dark mode nav: - - Introduction: "index.md" - - Contributing: "contributing.md" + - Introduction: "index.md" + - Contributing: "contributing.md" - - User Reference: - - "user/overview.md" - - "user/rules.md" - - "user/games.md" - - "user/features.md" - - "user/pbs-scores.md" - - "user/filter-directives.md" - - "user/lamps.md" - - "user/score-oddities.md" + - User Reference: + - "user/overview.md" + - "user/rules.md" + - "user/games.md" + - "user/features.md" + - "user/pbs-scores.md" + - "user/filter-directives.md" + - "user/lamps.md" + - "user/score-oddities.md" - - Statistics: - - "user/stats/tachi.md" - - "user/stats/esd.md" + - Statistics: + - "user/stats/tachi.md" + - "user/stats/esd.md" - - API Reference: - - "api/overview.md" - - "api/auth.md" - - "api/terminology.md" + - API Reference: + - "api/overview.md" + - "api/auth.md" + - "api/terminology.md" - - Endpoints: - - "api/routes/example.md" - - "api/routes/status.md" - - "api/routes/import.md" - - "api/routes/auth.md" - - "api/routes/users.md" - - "api/routes/user-gamept.md" - - "api/routes/user-integrations.md" - - "api/routes/sessions.md" - - "api/routes/scores.md" - - "api/routes/search.md" - - "api/routes/games.md" - - "api/routes/gpt.md" - - "api/routes/admin.md" - - "api/routes/ugpt-showcase.md" - - "api/routes/api-tokens.md" - - "api/routes/oauth2.md" - - "api/routes/oauth2-clients.md" + - Endpoints: + - "api/routes/example.md" + - "api/routes/status.md" + - "api/routes/import.md" + - "api/routes/auth.md" + - "api/routes/users.md" + - "api/routes/user-gamept.md" + - "api/routes/user-integrations.md" + - "api/routes/sessions.md" + - "api/routes/scores.md" + - "api/routes/search.md" + - "api/routes/games.md" + - "api/routes/gpt.md" + - "api/routes/admin.md" + - "api/routes/ugpt-showcase.md" + - "api/routes/api-tokens.md" + - "api/routes/oauth2.md" + - "api/routes/clients.md" - - Tachi Server Reference: - - "tachi-server/overview.md" - - "tachi-server/contributing.md" + - Tachi Server Reference: + - "tachi-server/overview.md" + - "tachi-server/contributing.md" - - Setup: - - "tachi-server/setup/setup.md" - - "tachi-server/setup/config.md" + - Setup: + - "tachi-server/setup/setup.md" + - "tachi-server/setup/config.md" - - Infrastructure: - - "tachi-server/infrastructure/toolchain.md" - - "tachi-server/infrastructure/logging.md" - - "tachi-server/infrastructure/branches.md" - - "tachi-server/infrastructure/versions.md" - - "tachi-server/infrastructure/oauth2.md" + - Infrastructure: + - "tachi-server/infrastructure/toolchain.md" + - "tachi-server/infrastructure/logging.md" + - "tachi-server/infrastructure/branches.md" + - "tachi-server/infrastructure/versions.md" + - "tachi-server/infrastructure/oauth2.md" + - "tachi-server/infrastructure/file-flow.md" - - Structure: - - "tachi-server/structure/style.md" - - "tachi-server/structure/filesystem.md" - - "tachi-server/structure/testing.md" + - Structure: + - "tachi-server/structure/style.md" + - "tachi-server/structure/filesystem.md" + - "tachi-server/structure/testing.md" - - BATCH-MANUAL: - - "tachi-server/batch-manual/overview.md" + - BATCH-MANUAL: + - "tachi-server/batch-manual/overview.md" - - Score Importing: - - "tachi-server/import/overview.md" - - "tachi-server/import/main.md" - - "tachi-server/import/import-types.md" - - "tachi-server/import/parse-conv.md" - - "tachi-server/import/conv-failures.md" - - "tachi-server/import/importing.md" - - "tachi-server/import/orphans.md" - - "tachi-server/import/parse-ipi.md" - - "tachi-server/import/sessions.md" - - "tachi-server/import/pbs.md" - - "tachi-server/import/ugs.md" - - "tachi-server/import/goals.md" - - "tachi-server/import/milestones.md" - - "tachi-server/import/import-doc-time.md" + - Score Importing: + - "tachi-server/import/overview.md" + - "tachi-server/import/main.md" + - "tachi-server/import/import-types.md" + - "tachi-server/import/parse-conv.md" + - "tachi-server/import/conv-failures.md" + - "tachi-server/import/importing.md" + - "tachi-server/import/orphans.md" + - "tachi-server/import/parse-ipi.md" + - "tachi-server/import/sessions.md" + - "tachi-server/import/pbs.md" + - "tachi-server/import/ugs.md" + - "tachi-server/import/goals.md" + - "tachi-server/import/milestones.md" + - "tachi-server/import/import-doc-time.md" - - Implementation Details: - - "tachi-server/implementation-details/details.md" - - "tachi-server/implementation-details/search.md" - - "tachi-server/implementation-details/statistics.md" - - "tachi-server/implementation-details/songs-charts.md" - - "tachi-server/implementation-details/game-configuration.md" - - "tachi-server/implementation-details/esd.md" - - "tachi-server/implementation-details/score-id.md" - - "tachi-server/implementation-details/goal-id.md" + - Implementation Details: + - "tachi-server/implementation-details/details.md" + - "tachi-server/implementation-details/search.md" + - "tachi-server/implementation-details/statistics.md" + - "tachi-server/implementation-details/songs-charts.md" + - "tachi-server/implementation-details/game-configuration.md" + - "tachi-server/implementation-details/esd.md" + - "tachi-server/implementation-details/score-id.md" + - "tachi-server/implementation-details/goal-id.md" - - Documents: - - "tachi-server/documents/overview.md" - - "tachi-server/documents/user.md" - - "tachi-server/documents/score.md" - - "tachi-server/documents/goal.md" - - "tachi-server/documents/user-goal.md" - - - Tachi Bot Reference: - - "tachi-bot/overview.md" + - Documents: + - "tachi-server/documents/overview.md" + - "tachi-server/documents/user.md" + - "tachi-server/documents/score.md" + - "tachi-server/documents/goal.md" + - "tachi-server/documents/user-goal.md" + + - Tachi Bot Reference: + - "tachi-bot/overview.md" markdown_extensions: - - admonition - - pymdownx.highlight - - pymdownx.superfences - - abbr - - pymdownx.snippets - - footnotes - - toc: - toc_depth: 2 - permalink: true - - pymdownx.arithmatex: - generic: true + - admonition + - pymdownx.highlight + - pymdownx.superfences + - abbr + - pymdownx.snippets + - footnotes + - toc: + toc_depth: 2 + permalink: true + - pymdownx.arithmatex: + generic: true extra_javascript: - - https://polyfill.io/v3/polyfill.min.js?features=es6 - - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js \ No newline at end of file + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js