Web authentication API: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
m (Gangsir moved page Web Authentication API to Web authentication API: Downcasing to style guide compliance.)
(Update possible return codes and values)
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Languages}}
<div align="center" class="stub">'''Category:''' [[Factorio_HTTP_API_usage_guidelines#Internal|Internal API]]</div>


Factorio's Web Authentication API endpoint gives you a token in exchange for your username and password, which is used by several other Factorio web API endpoints. The authentication endpoint is located at:
Factorio's Web Authentication API endpoint gives you a token in exchange for your username and password, which is used by several other Factorio web API endpoints. The authentication endpoint is located at:
Line 5: Line 5:
<code>https://auth.factorio.com/api-login</code>
<code>https://auth.factorio.com/api-login</code>


Authentication requires sending an HTTP POST request with these parameters:
Authentication requires sending an HTTP POST request (Content-Type: <code>application/x-www-form-urlencoded</code>) with these parameters:


{| class="wikitable"
{| class="wikitable"
| username
| username
| Required.
| Required.
| Account username.
| Account username or e-mail.
|-
|-
| password
| password
Line 17: Line 17:
|-  
|-  
| api_version
| api_version
| Not required.
| Default: 1
| Currently 2.
| Currently 6.
|-
|-
| require_game_ownership
| require_game_ownership
| Not required.
| Not required.
| If set to 'true', will fail authentication if the user account hasn't actually purchased Factorio.
| If set to 'true', will fail authentication if the user account hasn't actually purchased Factorio.
|-
| email_authentication_code
| Not required.
| If a previous login failed with <code>email-authentication-required</code>, email authentication can be completed by including the code sent to the user via mail.
|}
This endpoint always returns JSON encoded data.
{| class="wikitable"
|+ HTTP Status codes
|-
! API-Version
! Success
! Error
|-
! <= 3
| 200
| 401
|-
! >= 4
| 200
| 200
|}
|}


This endpoint always returns JSON encoded data. If authentication was successful, it will return an HTTP status code of 200 with a JSON list containing a single item: the auth token. The auth token seems to always be a hexadecimal encoded 15-byte string of random bytes.
{| class="wikitable"
|+ Success json
|-
! API-Version
! Name
! Value
|-
| <= 1
| []
| Array of hexadecimal encoded auth tokens
|-
| >= 2
| token
| Auth token is a hexadecimal encoded byte string
|-
| >= 2
| username
| The username of the logged in user.  
|}
 
{| class="wikitable"
|+ Error json
|-
! API-Version
! Name
! Value
|-
| all
| data
| Always empty object "{}"
|-
| all
| error
| Error codes like <code>login-failed</code> or <code>email-authentication-required</code>
|-
| all
| message
| A more detailed error message that can be shown to the user
|-
| <= 3
| status
| Same value as the Status Code
|}


TODO: exceptions and stuffs.
Clients causing a lot of errors like <code>login-failed</code> will be rate limited.


[[Category:Technical]]
[[Category:Technical]]

Latest revision as of 19:50, 3 October 2024

Category: Internal API

Factorio's Web Authentication API endpoint gives you a token in exchange for your username and password, which is used by several other Factorio web API endpoints. The authentication endpoint is located at:

https://auth.factorio.com/api-login

Authentication requires sending an HTTP POST request (Content-Type: application/x-www-form-urlencoded) with these parameters:

username Required. Account username or e-mail.
password Required. Account password.
api_version Default: 1 Currently 6.
require_game_ownership Not required. If set to 'true', will fail authentication if the user account hasn't actually purchased Factorio.
email_authentication_code Not required. If a previous login failed with email-authentication-required, email authentication can be completed by including the code sent to the user via mail.

This endpoint always returns JSON encoded data.

HTTP Status codes
API-Version Success Error
<= 3 200 401
>= 4 200 200
Success json
API-Version Name Value
<= 1 [] Array of hexadecimal encoded auth tokens
>= 2 token Auth token is a hexadecimal encoded byte string
>= 2 username The username of the logged in user.
Error json
API-Version Name Value
all data Always empty object "{}"
all error Error codes like login-failed or email-authentication-required
all message A more detailed error message that can be shown to the user
<= 3 status Same value as the Status Code

Clients causing a lot of errors like login-failed will be rate limited.

Retrieved from "https://wiki.factorio.com/index.php?title=Web_authentication_API&oldid=199955"