zk
e363bd2532
* docs: migrate from mkdocs to mdbook - Rename old mkdocs docs/ to old-docs/ for reference - Set up new docs/ with mdbook (book.toml + src/ tree) - Mirror full nav structure from mkdocs.yml into SUMMARY.md - Add Justfile-docs with docs-serve, docs-build, docs-check, docs-install recipes - Import Justfile-docs from root Justfile - Rewrite .github/workflows/docs.yml: build step uses taiki-e/install-action to install mdbook, split into separate build + deploy jobs, PR builds run the check step too * ci(docs): pin actions to SHAs, install mdbook via release binary * ci(docs): install mdbook from apt instead of curling a release binary * dev: replace mkdocs python stack with mdbook in dev image * ci(docs): apt only works on Debian; restore release binary install for Ubuntu CI * docs: fix duplicate file entries in SUMMARY.md * docs: remove docs-install recipe * docs: remove site-url from book.toml to fix asset loading * dev: install mdbook from upstream release binary, not Debian apt The Debian package (0.4.x+ds) strips bundled font assets, leaving the built site without fonts/fonts.css. Use the upstream tarball (same as CI) so the theme is complete. Handles x86_64 and aarch64. * docs: vendor mdbook tarballs in dev/mdbook/, install from there Dockerfile.dev uses COPY + tar to install the right arch at build time. CI extracts the x86_64 tarball directly from the checkout. No network access required for either — and no stripped-fonts Debian package. * fix: unwritten
5.1 KiB
API Client Management
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.
!!! warning All endpoints on this list require Self Key level authentication.
That is to say, it cannot be performed using Bearer tokens, and must be done by the user themselves.
Retrieve all clients you have created.
GET /api/v1/clients
Parameters
None.
Response
| Property | Type | Description |
| :: | :: | :: |
| <body> | Array<OAuth2ClientDoc> | All of the OAuth2 clients you have created. |
Example
Request
GET /api/v1/clients
Response
[{
"name": "My Client",
"clientID": "blah",
"clientSecret": "secret!!",
"requestPermissions": ["customise_profile"],
"author": 1,
"redirectUri": "https://example.com/callback",
},
// ...
]
Create a new OAuth2 Client
POST /api/v1/clients/create
Parameters
| Property | Type | Description |
| :: | :: | :: |
| name | String | A string between 3 and 80 characters. The name for this client. |
| redirectUri | Optional String (Valid URI) | Must be a HTTP/HTTPS URL, This is where users will be sent to after clicking Yes on the prompt. |
| webhookUri | Optional String (Valid URI) | Must be a HTTP/HTTPS URL. Registers this URL as a URL that wants webhook events to be sent to it. Read more about webhooks here. |
| apiKeyFormat | Optional String | If present, this sets an expected format for the API Key in Client File Flow. Must contain %%TACHI_KEY%%. |
| apiKeyFilename | Optional String | If present, this sets a filename fir Client File Flow. |
| permissions | Array<Permissions> | An array of permissions this client requests. You can check all permissions here. |
Response
| Property | Type | Description |
| :: | :: | :: |
| <body> | OAuth2ClientDoc | The OAuth2Client you just created. |
Example
Request
POST /api/v1/clients/create
{
"name": "My Client",
"redirectUri": "https://example.com/callback",
"permissions": ["customise_profile"]
}
Response
{
"name": "My Client",
"redirectUri": "https://example.com/callback",
"webhookUri": null,
"requestedPermissions": ["customise_profile"],
"clientID": "foobar",
"clientSecret": "secret_val",
"apiKeyFormat": null,
"apiKeyFilename": null
}
Retrieve information about a client
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.
Parameters
None.
Response
| Property | Type | Description |
| :: | :: | :: |
| <body> | OAuth2ClientDoc without clientSecret | The client document at this ID. |
Example
Request
GET /api/v1/clients/some_client_id
Response
{
"name": "My Client",
"redirectUri": "https://example.com/callback",
"webhookUri": null,
"requestedPermissions": ["customise_profile"],
"clientID": "foobar",
"clientSecret": "secret_val",
"apiKeyFormat": null,
"apiKeyFilename": null
}
Modify existing client
PATCH /api/v1/clients/:clientID
Permissions
- Must be the owner of this client.
Parameters
| Property | Type | Description |
| :: | :: | :: |
| name | String | A string between 3 and 80 characters. |
| webhookUri | String | A new webhookUri. |
| redirectUri | String | A new redirectUri. |
| apiKeyFormat | String | A new apiKeyFormat. |
| apiKeyFilename | String | A new apiKeyFilename. |
!!! note If you need to change permissions, you must make another client.
Also, all the above properties are optional. If not present, they will not be changed.
Response
| Property | Type | Description |
| :: | :: | :: |
| <body> | OAuth2ClientDoc | The new client document with the patched changes applied. |
Example
Request
PATCH /api/v1/clients/some_client_id
{
"name": "new name!"
}
Response
{
"name": "new name",
"clientID": "some_client_id",
// ... same props as in previous responses
}
Reset your client's secret.
POST /api/v1/clients/:clientID/reset-secret
!!! warning This does NOT reset api keys created by this client as per OAuth2 spec.
If you need that functionality, you will need to delete
your client.
Permissions
- Must be the owner of this client.
Parameters
None.
Response
| Property | Type | Description |
| :: | :: | :: |
| <body> | OAuth2ClientDoc | The new client document with the new secret. |
Example
Request
POST /api/v1/clients/some_client_id/reset-secret
Response
{
"name": "some client",
"clientID": "some_client_id",
"clientSecret": "FRESHLY_GENERATED_SECRET!",
// ... more props
}
Delete your client.
DELETE /api/v1/clients/:clientID
Permissions
- Must be the owner of this client.
Parameters
None.
Response
Empty Object.