mirror of
https://github.com/versia-pub/server.git
synced 2025-12-06 08:28:19 +01:00
139 lines
4.4 KiB
Markdown
139 lines
4.4 KiB
Markdown
# Frontend Authentication
|
|
|
|
Multiple API routes are exposed for authentication, to be used by frontend developers.
|
|
|
|
> [!INFO]
|
|
>
|
|
> These are different from the Client API routes, which are used by clients to interact with the Mastodon API.
|
|
|
|
A frontend is a web application that is designed to be the primary user interface for an instance. It is used also used by clients to perform authentication.
|
|
|
|
## Get Frontend Configuration
|
|
|
|
```http
|
|
GET /api/v1/frontend/config
|
|
```
|
|
|
|
Retrieves the frontend configuration for the instance. This returns whatever the `frontend.settings` object is set to in the Versia Server configuration.
|
|
|
|
This behaves like the `/api/v1/preferences` endpoint in the Mastodon API, but is specific to the frontend. These values are arbitrary and can be used for anything.
|
|
|
|
Frontend developers should always namespace their keys to avoid conflicts with other keys.
|
|
|
|
- **Returns**: Object with arbitrary keys and values.
|
|
- **Authentication**: Not required
|
|
- **Permissions**: None
|
|
- **Version History**:
|
|
- `0.7.0`: Added.
|
|
|
|
### Request
|
|
|
|
#### Example
|
|
|
|
```http
|
|
GET /api/v1/frontend/config
|
|
```
|
|
|
|
### Response
|
|
|
|
#### `200 OK`
|
|
|
|
Frontend configuration.
|
|
|
|
```json
|
|
{
|
|
"pub.versia.fe:theme": "dark",
|
|
"pub.versia.fe:custom_css": "body { background-color: black; }",
|
|
"net.googly.frontend:spoiler_image": "https://example.com/spoiler.png"
|
|
}
|
|
```
|
|
|
|
## Sign In
|
|
|
|
```http
|
|
POST /api/auth/login
|
|
```
|
|
|
|
Allows users to sign in to the instance. This is the first step in the authentication process.
|
|
|
|
- **Returns**: `302 Found` with a `Location` header to redirect the user to the next step, as well as a `Set-Cookie` header with the session JWT.
|
|
- **Authentication**: Not required
|
|
- **Permissions**: None
|
|
- **Version History**:
|
|
- `0.7.0`: First documented.
|
|
|
|
### Request
|
|
|
|
- `identifier` (string, required): The username or email of the user. Case-insensitive.
|
|
- `password` (string, required): The password of the user.
|
|
|
|
#### Query Parameters
|
|
|
|
- `client_id` (string, required): Client ID of the [application](https://docs.joinmastodon.org/entities/Application/) that is making the request.
|
|
- `redirect_uri` (string, required): Redirect URI of the [application](https://docs.joinmastodon.org/entities/Application/) that is making the request. Must match the saved value.
|
|
- `response_type` (string, required): Must be `code`.
|
|
- `scope` (string, required): OAuth2 scopes. Must match the value indicated in the [application](https://docs.joinmastodon.org/entities/Application/).
|
|
|
|
#### Example
|
|
|
|
```http
|
|
POST /api/auth/login?client_id=123&redirect_uri=https%3A%2F%2Fexample.com%2Fauth&response_type=code&scope=read%20write
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"identifier": "bobjones@gmail.com",
|
|
"password": "hunter2"
|
|
}
|
|
```
|
|
|
|
### Response
|
|
|
|
#### `302 Found`
|
|
|
|
Redirects the user to the consent page with some query parameters. The frontend should redirect the user to this URL.
|
|
|
|
This response also has a `Set-Cookie` header with a [JSON Web Token](https://jwt.io/) that contains the user's session information. This JWT is signed with the instance's secret key, and must be included in all subsequent authentication requests.
|
|
|
|
```http
|
|
HTTP/2.0 302 Found
|
|
Location: /oauth/consent?client_id=123&redirect_uri=https%3A%2F%2Fexample.com%2Fauth&response_type=code&scope=read%20write
|
|
Set-Cookie: jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=3600
|
|
```
|
|
|
|
## SSO Sign In
|
|
|
|
```http
|
|
POST /oauth/sso
|
|
```
|
|
|
|
Allows users to sign in to the instance using an external OpenID Connect provider.
|
|
|
|
- **Returns**: `302 Found` with a `Location` header to redirect the user to the next step.
|
|
- **Authentication**: Not required
|
|
- **Permissions**: None
|
|
- **Version History**:
|
|
- `0.7.0`: First documented.
|
|
|
|
### Request
|
|
|
|
#### Query Parameters
|
|
|
|
- `client_id` (string, required): Client ID of the [application](https://docs.joinmastodon.org/entities/Application/) that is making the request.
|
|
- `issuer` (string, required): The ID of the OpenID Connect provider, as found in `/api/{v1,v2}/instance`.
|
|
|
|
#### Example
|
|
|
|
```http
|
|
POST /oauth/sso?client_id=123&issuer=google
|
|
```
|
|
|
|
### Response
|
|
|
|
#### `302 Found`
|
|
|
|
Redirects the user to the OpenID Connect provider's login page.
|
|
|
|
```http
|
|
HTTP/2.0 302 Found
|
|
Location: https://accounts.google.com/o/oauth2/auth?client_id=123&redirect_uri=https%3A%2F%2Fexample.com%2Fauth&response_type=code&scope=openid%20email&state=123
|
|
``` |