post/auth/login

Login account

Authenticate with a password and either email (or login on email instances) or login (a username on username instances). Returns authentication token if credentials are valid and MFA is not required. If MFA is enabled, returns a ticket for MFA verification. Requires a solved captcha challenge (X-Captcha-Token).

login_user

Request body

application/json

json

{
  "type": "object",
  "properties": {
    "email": {
      "description": "Email address for authentication. Send this or login, not both",
      "$ref": "#/components/schemas/EmailType"
    },
    "login": {
      "description": "Sign-in identifier. An email address on email instances, a username on username instances",
      "type": "string"
    },
    "password": {
      "description": "Account password",
      "$ref": "#/components/schemas/PasswordType"
    },
    "invite_code": {
      "description": "Guild invite code to join after login",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "password"
  ]
}

Responses

200

Success

json

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/AuthTokenWithUserIdResponse"
    },
    {
      "type": "object",
      "properties": {
        "mfa": {
          "type": "boolean",
          "const": true,
          "description": "Indicates MFA is required to complete authentication"
        },
        "ticket": {
          "type": "string",
          "description": "MFA ticket to use when completing MFA verification"
        },
        "allowed_methods": {
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of allowed MFA methods"
        },
        "totp": {
          "type": "boolean",
          "description": "Whether TOTP authenticator MFA is available"
        },
        "webauthn": {
          "type": "boolean",
          "description": "Whether WebAuthn security key MFA is available"
        },
        "backup_codes": {
          "type": "boolean",
          "description": "Whether the account has at least one unconsumed backup code"
        }
      },
      "required": [
        "mfa",
        "ticket",
        "allowed_methods",
        "totp",
        "webauthn",
        "backup_codes"
      ],
      "additionalProperties": false
    }
  ]
}

400

Bad Request - The request was malformed or contained invalid data

json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Machine-readable error code"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "description": "Field-specific validation errors",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Field path that failed validation"
          },
          "code": {
            "description": "Machine-readable validation error code",
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "Human-readable validation error message"
          }
        },
        "required": [
          "path",
          "message"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": {}
}

429

Too Many Requests - You are being rate limited

json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Machine-readable error code"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "description": "Field-specific validation errors",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Field path that failed validation"
          },
          "code": {
            "description": "Machine-readable validation error code",
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "Human-readable validation error message"
          }
        },
        "required": [
          "path",
          "message"
        ],
        "additionalProperties": false
      }
    },
    "retry_after": {
      "type": "number",
      "description": "Seconds to wait before retrying"
    },
    "global": {
      "type": "boolean",
      "description": "Whether this is a global rate limit"
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": {}
}

500

Internal Server Error - An unexpected error occurred

json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Machine-readable error code"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "description": "Field-specific validation errors",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Field path that failed validation"
          },
          "code": {
            "description": "Machine-readable validation error code",
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "Human-readable validation error message"
          }
        },
        "required": [
          "path",
          "message"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": {}
}