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
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
GET /api/v1/frontend/config
Response
200 OK
Frontend configuration.
{
"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
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 aLocation
header to redirect the user to the next step, as well as aSet-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 that is making the request.redirect_uri
(string, required): Redirect URI of the application that is making the request. Must match the saved value.response_type
(string, required): Must becode
.scope
(string, required): OAuth2 scopes. Must match the value indicated in the application.
Example
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 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/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
POST /oauth/sso
Allows users to sign in to the instance using an external OpenID Connect provider.
- Returns:
302 Found
with aLocation
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 that is making the request.issuer
(string, required): The ID of the OpenID Connect provider, as found in/api/{v1,v2}/instance
.
Example
POST /oauth/sso?client_id=123&issuer=google
Response
302 Found
Redirects the user to the OpenID Connect provider's login page.
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