Authentication

We are not affiliated with floatplane.com / Floatplane Media / Linus Media Group. This is a community driven, open source project.

Authenticating a user results in a authentication token. You can use this token to make requests to the Floatplane API as if you were that user.

Authentication on Floatplane is done in one or two steps. Depending on the type of user account. The first step is username / password authentication. This step is always required for all people. Step two only applies to accounts with two-factor authentication enabled. Depending on the result of step one you will have to either do step two or not.

The floatplaneapi.com authentication pass through happens via a non Floatplane server hosted at Amazon. The connection from the client to AWS and from there to Flotplane is encrypted. Inside of the server the passwords and auth tokens are handled in plain text, as this is the only way that Floatplane can handle passwords / tokens. The source code for this server can be found here. It is theoretically possible for someone to steal passwords and tokens by modifying this server. Make sure to communicate this with your users.

We are working on a way to make a OAuth2 style way to interface with Floatplane. This will likely take a while. If you have any ideas or suggestions please contact us on Github.

Step 1: Username and password authentication

Once you have collected the username and password from the user via a login screen you need to send this information to the server to receive a authentication token.

post
Login with username and password

https://floatplaneapi.com/v1/auth/login
The request body should be JSON encoded.
Request
Response
Body Parameters
username
required
string
The users username
password
required
string
The users password
200: OK
//2FA enabled
{
"needs2FA": true,
"authorization": "s:-_aXJCoSvu-p9N8oRo5aoRJB0yg9r0nm.hC02y6dSJT35JmTBTcFKhYDNDRfHUC3hfe6dG9QbWZ0"
}
‚Äč
//2FA not enabled
{
"user": {
"id": "5c4dda93ff5da432730949fa",
"username": "joe1",
"profileImage": {
"width": 512,
"height": 512,
"path": "https://pbs.floatplanecdn.com/profile_images/default/user2.png",
"childImages": [{
"width": 250,
"height": 250,
"path": "https://pbs.floatplanecdn.com/profile_images/default/user2_250x250.png"
}, {
"width": 100,
"height": 100,
"path": "https://pbs.floatplanecdn.com/profile_images/default/user2_100x100.png"
}]
}
},
"needs2FA": false,
"authorization": "s:-_aXJCoSvu-p9N8oRo5aoRJB0yg9r0nm.hC02y6dSJT35JmTBTcFKhYDNDRfHUC3hfe6dG9QbWZ0"
}
400: Bad Request
{
"error": "username or password not supplied or misformed"
}
401: Unauthorized
{
"error": "username or password incorrect"
}
500: Internal Server Error
{
"error": "internal server error"

In the response from the server there are two fields that are important. That is the authentication field and the needs2fa field. The authentication field is the authentication token that you can use to make authenticated API requests. You will need this token in a minute. Make sure to save it. The needs2fa field tells you if you have to do the second authentication step. If needs2fa is set to true please continue with Step 2. If needs2fa is set to false you are done with authentication. Your authentication token is now active.

Step 2: Second factor authentication (token)

You now need to collect the two factor authentication token. This is either a 6 digit number or an 8 letter string. Once you have collected the token you need to send it off to the server together with the authentication token from step one. This will activate that token.

post
2FA token check

https://floatplaneapi.com/v1/auth/check2fa
The request body should be JSON encoded.
Request
Response
Headers
x-fpapi-token
required
string
This is the authentication token that needs to be activated.
Body Parameters
token
required
string
This is the two-factor authentication code.
200: OK
{
"user": {
"id": "5c4dda93ff5da432730949fa",
"username": "joe1",
"profileImage": {
"width": 512,
"height": 512,
"path": "https://pbs.floatplanecdn.com/profile_images/default/user2.png",
"childImages": [{
"width": 250,
"height": 250,
"path": "https://pbs.floatplanecdn.com/profile_images/default/user2_250x250.png"
}, {
"width": 100,
"height": 100,
"path": "https://pbs.floatplanecdn.com/profile_images/default/user2_100x100.png"
}]
}
},
"needs2FA": false
}
400: Bad Request
{
"id": "lgvx-h5zw-rjs1",
"errors": [{
"id": "lgvx-h5zw-rjs1",
"name": "paramValidationError",
"message": "\"token\" with value \"51285\" fails to match the required pattern: /(^[0-9]{6}$)|(^[a-zA-Z0-9]{12}$)|(^[a-zA-Z0-9]{6}-[a-zA-Z0-9]{6}$)/",
"data": {
"rule": "string.regex.base"
}
}],
"message": "\"token\" with value \"51285\" fails to match the required pattern: /(^[0-9]{6}$)|(^[a-zA-Z0-9]{12}$)|(^[a-zA-Z0-9]{6}-[a-zA-Z0-9]{6}$)/"
}
401: Unauthorized
{
"id": "bkyt-d7qu-qks1",
"errors": [{
"id": "bkyt-d7qu-qks1",
"name": "invalid2faTokenError",
"message": "Invalid two factor authentication token."
}],
"message": "Invalid two factor authentication token."
}
500: Internal Server Error
{
"error": "internal server error"
}

If you are getting a "Missing required parameter: twoFactor" __error your authentication token is not valid. Make sure you successfully completed step one before continuing to step two.

You are now done with authentication. You have a valid authentication token. You can use this token to make authenticated API requests.