Skip to content
MemGhost MemGhost Docs
memghost.com Open App

Authenticate user and create session

POST
/auth/login

Authenticates a user with username and password, creates a new session, and returns JWT access and refresh tokens.

This is a command that returns 202 Accepted. The session is created asynchronously, but tokens are returned synchronously for immediate use.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
object
username
required

Username for authentication

string
>= 1 characters <= 255 characters
Example
alice
password
required

User password

string format: password
>= 8 characters <= 128 characters
Example
securepassword123
Examples
{
  "username": "alice",
  "password": "securepassword123"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Login successful, session created

object
access_token
required

JWT access token (valid for 1 hour)

string
Example
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
refresh_token
required

JWT refresh token (valid for 90 days)

string
Example
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
expires_in
required

Access token expiration time in seconds

integer
Example
3600
token_type
required

Token type (always “Bearer”)

string
Example
Bearer
session_id
required

Session identifier

string format: uuid
Example
123e4567-e89b-12d3-a456-426614174000
Examples
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "session_id": "123e4567-e89b-12d3-a456-426614174000"
}

Headers

Section titled “Headers ”
Location
string
Example
/api/v1/auth/session/{session_id}

URL to the created session resource

400

Section titled “400 ”

Bad request (invalid parameters)

object
error
required

Error code

string
Allowed values: validation_error not_found version_conflict internal_error invalid_request unauthorized rate_limit_exceeded
Example
unauthorized
message
required

Human-readable error message

string
Example
Invalid username or password
details

Additional error details (field-level validation errors, etc.)

object
key
additional properties
any
Examples
{
  "error": "validation_error",
  "message": "Invalid request parameters",
  "details": {
    "username": "Username is required",
    "password": "Password must be at least 8 characters"
  }
}

401

Section titled “401 ”

Invalid credentials

object
error
required

Error code

string
Allowed values: validation_error not_found version_conflict internal_error invalid_request unauthorized rate_limit_exceeded
Example
unauthorized
message
required

Human-readable error message

string
Example
Invalid username or password
details

Additional error details (field-level validation errors, etc.)

object
key
additional properties
any
Examples
{
  "error": "unauthorized",
  "message": "Invalid username or password"
}

429

Section titled “429 ”

Too many login attempts

object
error
required

Error code

string
Allowed values: validation_error not_found version_conflict internal_error invalid_request unauthorized rate_limit_exceeded
Example
unauthorized
message
required

Human-readable error message

string
Example
Invalid username or password
details

Additional error details (field-level validation errors, etc.)

object
key
additional properties
any
Examples
{
  "error": "rate_limit_exceeded",
  "message": "Too many login attempts. Please try again later."
}

500

Section titled “500 ”

Internal server error

object
error
required

Error code

string
Allowed values: validation_error not_found version_conflict internal_error invalid_request unauthorized rate_limit_exceeded
Example
unauthorized
message
required

Human-readable error message

string
Example
Invalid username or password
details

Additional error details (field-level validation errors, etc.)

object
key
additional properties
any
Examples
{
  "error": "internal_error",
  "message": "An internal error occurred"
}