Authentication

The Soup API uses Bearer token authentication.

Getting a Token

Self-Hosted (Local Password)

Check Setup Status

GET /api/v1/auth/setup

Response:

{
  "data": {
    "is_setup": false
  }
}

Initial Setup

Only works once, when is_setup is false:

POST /api/v1/auth/setup
Content-Type: application/json

{
  "password": "your-secure-password"
}

Response:

{
  "data": {
    "token": "abc123...",
    "user": {
      "id": "user_abc123",
      "email": "admin@localhost",
      "name": "Admin"
    }
  }
}

Login

POST /api/v1/auth/login
Content-Type: application/json

{
  "password": "your-password"
}

Response:

{
  "data": {
    "token": "abc123...",
    "user": {
      "id": "user_abc123",
      "email": "admin@localhost",
      "name": "Admin"
    }
  }
}

Change Password

Requires authentication.

POST /api/v1/auth/change-password
Authorization: Bearer <token>
Content-Type: application/json

{
  "current_password": "old-password",
  "new_password": "new-password"
}

Response: 204 No Content

Cloud (Magic Link)

Request Code

POST /api/v1/auth/request-code
Content-Type: application/json

{
  "email": "user@example.com"
}

Response:

{
  "data": {
    "message": "Code sent to your email"
  }
}

Verify Code

POST /api/v1/auth/verify-code
Content-Type: application/json

{
  "email": "user@example.com",
  "code": "123456"
}

Response:

{
  "data": {
    "token": "abc123...",
    "user": {
      "id": "user_abc123",
      "email": "user@example.com",
      "name": null
    }
  }
}

Dev Mode

In development mode (ENV != production), the code 000000 always works.

Using Tokens

Include the token in the Authorization header:

curl -H "Authorization: Bearer <token>" \
  https://api.soup.dev/api/v1/projects

Token Properties

• Tokens don’t expire by default
• Tokens are stored as SHA-256 hashes (the raw token is only shown once)
• Each login creates a new token
• Old tokens remain valid until explicitly revoked

Get Current User

GET /api/v1/me
Authorization: Bearer <token>

Response:

{
  "data": {
    "id": "user_abc123",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Error Responses

Invalid Token

{
  "error": "invalid token"
}

Status: 401 Unauthorized

Missing Token

{
  "error": "unauthorized"
}

Status: 401 Unauthorized