mirror of
https://github.com/superseriousbusiness/gotosocial
synced 2025-06-05 21:59:39 +02:00
[feature] Application creation + management via API + settings panel (#3906)
* [feature] Application creation + management via API + settings panel * fix docs links * add errnorows test * use known application as shorter * add comment about side effects
This commit is contained in:
tobi
GitHub
@@ -2,6 +2,9 @@
|
||||
|
||||
Using the client API requires authentication. This page documents the general flow for retrieving an authentication token with examples for doing this on the CLI using `curl`.
|
||||
|
||||
!!! tip
|
||||
If you want to get an API access token via the settings panel instead, without having to use the command line, see the [Application documentation](https://docs.gotosocial.org/en/latest/user_guide/settings/#applications).
|
||||
|
||||
## Create a new application
|
||||
|
||||
We need to register a new application, which we can then use to request an OAuth token. This is done by making a `POST` request to the `/api/v1/apps` endpoint. Replace `your_app_name` in the command below with the name you want to use for your application:
|
||||
@@ -19,18 +22,15 @@ curl \
|
||||
|
||||
The string `urn:ietf:wg:oauth:2.0:oob` is an indication of what is known as out-of-band authentication - a technique used in multi-factor authentication to reduce the number of ways that a bad actor can intrude on the authentication process. In this instance, it allows us to view and manually copy the tokens created to use further in this process.
|
||||
|
||||
Note that `scopes` can be any space-separated combination of:
|
||||
|
||||
- `read`
|
||||
- `write`
|
||||
- `admin`
|
||||
!!! tip "Scopes"
|
||||
It is always good practice to grant your application the lowest tier permissions it needs to do its job. e.g. If your application won't be making posts, use `scope=read` or even a subscope of that.
|
||||
|
||||
In this spirit, "read" is used in the example above, which means that the application will be restricted to only being able to do "read" actions.
|
||||
|
||||
For a list of available scopes, see [the swagger docs](https://docs.gotosocial.org/en/latest/api/swagger/).
|
||||
|
||||
!!! warning
|
||||
GoToSocial does not currently support scoped authorization tokens, so any token you obtain in this process will be able to perform all actions on your behalf, including admin actions if your account has admin permissions. Nevertheless, it is always good practice to grant your application the lowest tier permissions it needs to do its job. e.g. If your application won't be making posts, use scope=read.
|
||||
|
||||
In this spirit, "read" is used in the example above, which means that in the future when scoped tokens are supported, the application will be restricted to only being able to do "read" actions.
|
||||
|
||||
You can read more about additional planned OAuth security features [right here](https://github.com/superseriousbusiness/gotosocial/issues/2232).
|
||||
GoToSocial did not support scoped authorization tokens before version 0.19.0, so if you are using a version of GoToSocial below that, then any token you obtain in this process will be able to perform all actions on your behalf, including admin actions if your account has admin permissions.
|
||||
|
||||
A successful call returns a response with a `client_id` and `client_secret`, which we are going need to use in the rest of the process. It looks something like this:
|
||||
|
||||
@@ -126,7 +126,6 @@ See this example:
|
||||
|
||||
```bash
|
||||
curl \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
|
||||
'https://example.org/api/v1/accounts/verify_credentials'
|
||||
```
|
||||
@@ -140,7 +139,6 @@ For example, you can issue another `GET` request to the API using the same acces
|
||||
|
||||
```bash
|
||||
curl \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
|
||||
'https://example.org/api/v1/notifications'
|
||||
```
|
||||
|
||||
@@ -828,6 +828,11 @@ definitions:
|
||||
description: Client secret associated with this application.
|
||||
type: string
|
||||
x-go-name: ClientSecret
|
||||
created_at:
|
||||
description: When the application was created. (ISO 8601 Datetime)
|
||||
example: "2021-07-30T09:20:25+00:00"
|
||||
type: string
|
||||
x-go-name: CreatedAt
|
||||
id:
|
||||
description: The ID of the application.
|
||||
example: 01FBVD42CQ3ZEEVMW180SBX03B
|
||||
@@ -3649,6 +3654,54 @@ info:
|
||||
contact:
|
||||
email: admin@gotosocial.org
|
||||
name: GoToSocial Authors
|
||||
description: |-
|
||||
This document describes the GoToSocial HTTP API.
|
||||
|
||||
For information on how to authenticate with the API using an OAuth access token, see the documentation here: https://docs.gotosocial.org/en/latest/api/authentication/.
|
||||
|
||||
Available scopes are:
|
||||
|
||||
admin: grants admin access to everything
|
||||
admin:read: grants admin read access to everything
|
||||
admin:read:accounts: grants admin read access to accounts
|
||||
admin:read:domain_allows: grants admin read access to domain_allows
|
||||
admin:read:domain_blocks: grants admin read access to domain_blocks
|
||||
admin:read:reports: grants admin read access to reports
|
||||
admin:write: grants admin write access to everything
|
||||
admin:write:accounts: grants write read access to accounts
|
||||
admin:write:domain_allows: grants admin write access to domain_allows
|
||||
admin:write:domain_blocks: grants write read access to domain_blocks
|
||||
admin:write:reports: grants admin write access to reports
|
||||
profile: grants read access to verify_credentials
|
||||
push: grants read/write access to push
|
||||
read: grants read access to everything
|
||||
read:accounts: grants read access to accounts
|
||||
read:applications: grants read access to user-managed applications
|
||||
read:blocks: grants read access to blocks
|
||||
read:bookmarks: grants read access to bookmarks
|
||||
read:favourites: grants read access to accounts
|
||||
read:filters: grants read access to filters
|
||||
read:follows: grants read access to follows
|
||||
read:lists: grants read access to lists
|
||||
read:mutes: grants read access to mutes
|
||||
read:notifications: grants read access to notifications
|
||||
read:search: grants read access to search
|
||||
read:statuses: grants read access to statuses
|
||||
write: grants write access to everything
|
||||
write:accounts: grants write access to accounts
|
||||
write:applications: grants write access to user-managed applications
|
||||
write:blocks: grants write access to blocks
|
||||
write:bookmarks: grants write access to bookmarks
|
||||
write:conversations: grants write access to conversations
|
||||
write:favourites: grants write access to favourites
|
||||
write:filters: grants write access to filters
|
||||
write:follows: grants write access to follows
|
||||
write:lists: grants write access to lists
|
||||
write:media: grants write access to media
|
||||
write:mutes: grants write access to mutes
|
||||
write:notifications: grants write access to notifications
|
||||
write:reports: grants write access to reports
|
||||
write:statuses: grants write access to statuses
|
||||
license:
|
||||
name: AGPL3
|
||||
url: https://www.gnu.org/licenses/agpl-3.0.en.html
|
||||
@@ -7484,6 +7537,63 @@ paths:
|
||||
tags:
|
||||
- announcements
|
||||
/api/v1/apps:
|
||||
get:
|
||||
description: |-
|
||||
The next and previous queries can be parsed from the returned Link header.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
<https://example.org/api/v1/apps?limit=80&max_id=01FC0SKA48HNSVR6YKZCQGS2V8>; rel="next", <https://example.org/api/v1/apps?limit=80&min_id=01FC0SKW5JK2Q4EVAV2B462YY0>; rel="prev"
|
||||
````
|
||||
operationId: appsGet
|
||||
parameters:
|
||||
- description: Return only items *OLDER* than the given max item ID. The item with the specified ID will not be included in the response.
|
||||
in: query
|
||||
name: max_id
|
||||
type: string
|
||||
- description: Return only items *newer* than the given since item ID. The item with the specified ID will not be included in the response.
|
||||
in: query
|
||||
name: since_id
|
||||
type: string
|
||||
- description: Return only items *immediately newer* than the given since item ID. The item with the specified ID will not be included in the response.
|
||||
in: query
|
||||
name: min_id
|
||||
type: string
|
||||
- default: 20
|
||||
description: Number of items to return.
|
||||
in: query
|
||||
name: limit
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: ""
|
||||
headers:
|
||||
Link:
|
||||
description: Links to the next and previous queries.
|
||||
type: string
|
||||
schema:
|
||||
items:
|
||||
$ref: '#/definitions/application'
|
||||
type: array
|
||||
"400":
|
||||
description: bad request
|
||||
"401":
|
||||
description: unauthorized
|
||||
"404":
|
||||
description: not found
|
||||
"406":
|
||||
description: not acceptable
|
||||
"500":
|
||||
description: internal server error
|
||||
security:
|
||||
- OAuth2 Bearer:
|
||||
- read:applications
|
||||
summary: Get an array of applications that are managed by the requester.
|
||||
tags:
|
||||
- apps
|
||||
post:
|
||||
consumes:
|
||||
- application/json
|
||||
@@ -7493,8 +7603,10 @@ paths:
|
||||
The registered application can be used to obtain an application token.
|
||||
This can then be used to register a new account, or (through user auth) obtain an access token.
|
||||
|
||||
The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'.
|
||||
The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'.
|
||||
If the application was registered with a Bearer token passed in the Authorization header, the created application will be managed by the authenticated user (must have scope write:applications).
|
||||
|
||||
Parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'.
|
||||
Parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'.
|
||||
operationId: appCreate
|
||||
parameters:
|
||||
- description: The name of the application.
|
||||
@@ -7548,6 +7660,69 @@ paths:
|
||||
summary: Register a new application on this instance.
|
||||
tags:
|
||||
- apps
|
||||
/api/v1/apps/{id}:
|
||||
delete:
|
||||
operationId: appDelete
|
||||
parameters:
|
||||
- description: The id of the application to delete.
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: string
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: The deleted application.
|
||||
schema:
|
||||
$ref: '#/definitions/application'
|
||||
"400":
|
||||
description: bad request
|
||||
"401":
|
||||
description: unauthorized
|
||||
"404":
|
||||
description: not found
|
||||
"406":
|
||||
description: not acceptable
|
||||
"500":
|
||||
description: internal server error
|
||||
security:
|
||||
- OAuth2 Bearer:
|
||||
- write:applications
|
||||
summary: Delete a single application managed by the requester.
|
||||
tags:
|
||||
- apps
|
||||
get:
|
||||
operationId: appGet
|
||||
parameters:
|
||||
- description: The id of the requested application.
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: string
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: The requested application.
|
||||
schema:
|
||||
$ref: '#/definitions/application'
|
||||
"400":
|
||||
description: bad request
|
||||
"401":
|
||||
description: unauthorized
|
||||
"404":
|
||||
description: not found
|
||||
"406":
|
||||
description: not acceptable
|
||||
"500":
|
||||
description: internal server error
|
||||
security:
|
||||
- OAuth2 Bearer:
|
||||
- read:applications
|
||||
summary: Get a single application managed by the requester.
|
||||
tags:
|
||||
- apps
|
||||
/api/v1/blocks:
|
||||
get:
|
||||
description: |-
|
||||
@@ -11705,15 +11880,15 @@ paths:
|
||||
````
|
||||
operationId: tokensInfoGet
|
||||
parameters:
|
||||
- description: Return only items *OLDER* than the given max status ID. The item with the specified ID will not be included in the response.
|
||||
- description: Return only items *OLDER* than the given max item ID. The item with the specified ID will not be included in the response.
|
||||
in: query
|
||||
name: max_id
|
||||
type: string
|
||||
- description: Return only items *newer* than the given since status ID. The item with the specified ID will not be included in the response.
|
||||
- description: Return only items *newer* than the given since item ID. The item with the specified ID will not be included in the response.
|
||||
in: query
|
||||
name: since_id
|
||||
type: string
|
||||
- description: Return only items *immediately newer* than the given since status ID. The item with the specified ID will not be included in the response.
|
||||
- description: Return only items *immediately newer* than the given since item ID. The item with the specified ID will not be included in the response.
|
||||
in: query
|
||||
name: min_id
|
||||
type: string
|
||||
@@ -12927,6 +13102,7 @@ securityDefinitions:
|
||||
push: grants read/write access to push
|
||||
read: grants read access to everything
|
||||
read:accounts: grants read access to accounts
|
||||
read:applications: grants read access to user-managed applications
|
||||
read:blocks: grants read access to blocks
|
||||
read:bookmarks: grants read access to bookmarks
|
||||
read:favourites: grants read access to accounts
|
||||
@@ -12939,6 +13115,7 @@ securityDefinitions:
|
||||
read:statuses: grants read access to statuses
|
||||
write: grants write access to everything
|
||||
write:accounts: grants write access to accounts
|
||||
write:applications: grants write access to user-managed applications
|
||||
write:blocks: grants write access to blocks
|
||||
write:bookmarks: grants write access to bookmarks
|
||||
write:conversations: grants write access to conversations
|
||||
|
||||
Reference in New Issue
Block a user