Skip to main content

​
Overview

Asta uses JWT (JSON Web Token) based authentication. After logging in, include the token in the Authorization header for subsequent requests.

​
Authorization Header Format

Authorization: Bearer <your-jwt-token>

​
Login

curl -X POST https://api.asta.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "your-password"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-123",
    "username": "[email protected]",
    "role": "user"
  }
}

​
POST /api/auth/login

Authenticate a user and receive a JWT access token.

​
Request Body

​
username
string
required
The user’s username or email address
​
password
string
required
The user’s password

​
Response

​
access_token
string
JWT token for authenticating subsequent requests. Include in the Authorization: Bearer <token> header.
​
user
object
User information object

​
Error Responses

  • 401 Unauthorized: Invalid username or password

​
Register

curl -X POST https://api.asta.app/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "secure-password"
  }'

{
  "user": {
    "id": "user-456",
    "username": "[email protected]",
    "role": "user"
  }
}

​
POST /api/auth/register

Create a new user account with the user role. Registration is only available when multi-user mode is active.

​
Request Body

​
username
string
required
Username for the new account (minimum 2 characters)
​
password
string
required
Password for the new account (minimum 4 characters)

​
Response

​
user
object
Newly created user information

​
Error Responses

  • 400 Bad Request: Username too short (< 2 characters) or password too short (< 4 characters)
  • 403 Forbidden: Registration is not available (multi-user mode not active)
  • 409 Conflict: Username already exists

​
Get Current User

curl https://api.asta.app/api/auth/me \
  -H "Authorization: Bearer <your-jwt-token>"

{
  "id": "user-123",
  "username": "[email protected]",
  "role": "user"
}

​
GET /api/auth/me

Retrieve information about the currently authenticated user.

​
Response

​
id
string
Unique user identifier
​
username
string
The user’s username
​
role
string
User role: "admin" or "user"

​
Change Password

curl -X POST https://api.asta.app/api/auth/change-password \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "old-password",
    "new_password": "new-secure-password"
  }'

{
  "ok": true
}

​
POST /api/auth/change-password

Change the password for the currently authenticated user.

​
Request Body

​
current_password
string
required
The user’s current password for verification
​
new_password
string
required
The new password to set

​
Response

​
ok
boolean
Returns true if password was changed successfully

​
Error Responses

  • 401 Unauthorized: Current password is incorrect
  • 404 Not Found: User not found

​
Admin Endpoints

The following endpoints require admin privileges.

​
List Users

​
GET /api/auth/users

List all users in the system. Requires admin role. 
curl https://api.asta.app/api/auth/users \
  -H "Authorization: Bearer <admin-jwt-token>"

{
  "users": [
    {
      "id": "user-123",
      "username": "[email protected]",
      "role": "admin"
    },
    {
      "id": "user-456",
      "username": "[email protected]",
      "role": "user"
    }
  ]
}
​
users
array
Array of user objects

​
Create User

​
POST /api/auth/users

Create a new user with a specified role. Requires admin role. 
curl -X POST https://api.asta.app/api/auth/users \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "secure-password",
    "role": "admin"
  }'
​
username
string
required
Username for the new account
​
password
string
required
Password for the new account (minimum 4 characters)
​
role
string
default:"user"
User role: "admin" or "user"

​
Error Responses

  • 400 Bad Request: Invalid role or password too short
  • 409 Conflict: Username already exists

​
Delete User

​
DELETE /api/auth/users/

Delete a user by ID. Requires admin role. You cannot delete yourself. 
curl -X DELETE https://api.asta.app/api/auth/users/user-456 \
  -H "Authorization: Bearer <admin-jwt-token>"
​
user_id
string
required
The ID of the user to delete

​
Error Responses

  • 400 Bad Request: Cannot delete yourself
  • 404 Not Found: User not found

​
Reset User Password

​
PUT /api/auth/users//reset-password

Reset another user’s password. Requires admin role. 
curl -X PUT https://api.asta.app/api/auth/users/user-456/reset-password \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "new_password": "new-secure-password"
  }'
​
user_id
string
required
The ID of the user whose password to reset
​
new_password
string
required
The new password to set (minimum 4 characters)

​
Error Responses

  • 400 Bad Request: Password too short
  • 404 Not Found: User not found

Build docs developers (and LLMs) love

Get started for freeTalk to us