Russell Ballestrini
5a5bd57bc3
* editors can invite log emitting agents without mailboxes using JWT tokens. * guests can read logs from public namespaces. modified: app.py modified: openapi.yaml modified: templates/base.html.j2 modified: templates/home.html.j2 modified: templates/manage_namespace.html.j2
603 lines
17 KiB
YAML
603 lines
17 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: PyraLogs API
|
|
version: 1.0.0
|
|
description: |
|
|
API specification for the PyraLogs application.
|
|
PyraLogs allows users to register, authenticate, manage namespaces,
|
|
generate JWT tokens for agents, and submit logs via a webhook.
|
|
servers:
|
|
- url: http://127.0.0.1:{port}
|
|
description: Local development server
|
|
variables:
|
|
port:
|
|
default: '6544'
|
|
- url: https://logs.unturf.com
|
|
description: Production server
|
|
|
|
paths:
|
|
/:
|
|
get:
|
|
summary: Home Page
|
|
description: Displays the home page with public namespaces and user namespaces.
|
|
responses:
|
|
'200':
|
|
description: Successful response
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
|
|
/auth/login:
|
|
get:
|
|
summary: Display Login Page
|
|
description: Renders the login page where users can enter their email.
|
|
responses:
|
|
'200':
|
|
description: Login page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
post:
|
|
summary: Process Login
|
|
description: Sends a verification code to the user's email.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
email:
|
|
type: string
|
|
format: email
|
|
required:
|
|
- email
|
|
responses:
|
|
'302':
|
|
description: Redirects to the verification page
|
|
headers:
|
|
Location:
|
|
description: URL of the verification page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., email missing)
|
|
'500':
|
|
description: Internal Server Error
|
|
|
|
/auth/verify:
|
|
get:
|
|
summary: Display Verification Page
|
|
description: Renders the verification page where users can enter their code.
|
|
responses:
|
|
'200':
|
|
description: Verification page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
post:
|
|
summary: Verify User
|
|
description: Verifies the user's code and logs them in.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
required:
|
|
- code
|
|
responses:
|
|
'302':
|
|
description: Redirects to the home page upon successful verification
|
|
headers:
|
|
Location:
|
|
description: URL of the home page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., invalid code)
|
|
'500':
|
|
description: Internal Server Error
|
|
|
|
/auth/logout:
|
|
post:
|
|
summary: Logout User
|
|
description: Logs out the current user.
|
|
security:
|
|
- sessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
csrf_token:
|
|
type: string
|
|
responses:
|
|
'302':
|
|
description: Redirects to the home page
|
|
headers:
|
|
Location:
|
|
description: URL of the home page
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Unauthorized (user not logged in)
|
|
|
|
/auth/profile:
|
|
get:
|
|
summary: Display User Profile
|
|
description: Shows the user's profile, including owned namespaces.
|
|
security:
|
|
- sessionAuth: []
|
|
responses:
|
|
'200':
|
|
description: Profile page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Unauthorized (user not logged in)
|
|
post:
|
|
summary: Update User Profile
|
|
description: Updates the user's profile settings.
|
|
security:
|
|
- sessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
enable_gravatar:
|
|
type: string
|
|
enum: ['on']
|
|
new_username:
|
|
type: string
|
|
required:
|
|
- new_username
|
|
encoding:
|
|
enable_gravatar:
|
|
contentType: text/plain
|
|
new_username:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the profile page
|
|
headers:
|
|
Location:
|
|
description: URL of the profile page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., username already in use)
|
|
'403':
|
|
description: Unauthorized (user not logged in or guest mode)
|
|
|
|
/namespace/create:
|
|
get:
|
|
summary: Display Namespace Creation Page
|
|
description: Renders the form to create a new namespace.
|
|
security:
|
|
- sessionAuth: []
|
|
responses:
|
|
'200':
|
|
description: Namespace creation page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Unauthorized (user not logged in)
|
|
post:
|
|
summary: Create Namespace
|
|
description: Processes the namespace creation form.
|
|
security:
|
|
- sessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
is_public:
|
|
type: string
|
|
enum: ['on']
|
|
encoding:
|
|
name:
|
|
contentType: text/plain
|
|
is_public:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the namespace management page
|
|
headers:
|
|
Location:
|
|
description: URL of the namespace management page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., namespace name already exists)
|
|
'403':
|
|
description: Unauthorized (user not logged in)
|
|
|
|
/namespace/{namespace_short_id}/manage:
|
|
get:
|
|
summary: Manage Namespace
|
|
description: Displays the namespace management page (owners only).
|
|
security:
|
|
- sessionAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
responses:
|
|
'200':
|
|
description: Namespace management page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace not found
|
|
|
|
/namespace/{namespace_short_id}/update:
|
|
post:
|
|
summary: Update Namespace
|
|
description: Updates namespace properties (owners only).
|
|
security:
|
|
- sessionAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
is_public:
|
|
type: string
|
|
enum: ['on']
|
|
description: 'Checkbox value. Present if checked.'
|
|
encoding:
|
|
is_public:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the namespace management page
|
|
headers:
|
|
Location:
|
|
description: URL of the namespace management page
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace not found
|
|
|
|
/namespace/{namespace_short_id}/invite:
|
|
post:
|
|
summary: Invite User to Namespace
|
|
description: Invites a user to the namespace with a specified role (owners only).
|
|
security:
|
|
- sessionAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
email:
|
|
type: string
|
|
format: email
|
|
role:
|
|
type: string
|
|
enum: ['owner', 'editor', 'reader']
|
|
required:
|
|
- email
|
|
- role
|
|
encoding:
|
|
email:
|
|
contentType: text/plain
|
|
role:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the namespace management page
|
|
headers:
|
|
Location:
|
|
description: URL of the namespace management page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., invalid role)
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace not found
|
|
|
|
/namespace/{namespace_short_id}/remove_user:
|
|
post:
|
|
summary: Remove User from Namespace
|
|
description: Removes a user from the namespace (owners only, cannot remove self).
|
|
security:
|
|
- sessionAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: string
|
|
required:
|
|
- user_id
|
|
encoding:
|
|
user_id:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the namespace management page
|
|
headers:
|
|
Location:
|
|
description: URL of the namespace management page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., cannot remove self)
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace or user not found
|
|
|
|
/namespace/{namespace_short_id}/change_member_role:
|
|
post:
|
|
summary: Change Member Role in Namespace
|
|
description: Changes a member's role in the namespace (owners only, cannot change own role).
|
|
security:
|
|
- sessionAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: string
|
|
role:
|
|
type: string
|
|
enum: ['owner', 'editor', 'reader']
|
|
required:
|
|
- user_id
|
|
- role
|
|
encoding:
|
|
user_id:
|
|
contentType: text/plain
|
|
role:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the namespace management page
|
|
headers:
|
|
Location:
|
|
description: URL of the namespace management page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., cannot change own role)
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace or user not found
|
|
|
|
/namespace/{namespace_short_id}/generate_agent_jwt:
|
|
post:
|
|
summary: Generate Agent JWT
|
|
description: Generates a JWT token for an agent (owners only).
|
|
security:
|
|
- sessionAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
agent_name:
|
|
type: string
|
|
required:
|
|
- agent_name
|
|
encoding:
|
|
agent_name:
|
|
contentType: text/plain
|
|
responses:
|
|
'200':
|
|
description: Agent JWT generated and displayed
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., agent name missing)
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace not found
|
|
|
|
/namespace/{namespace_short_id}/revoke_agent:
|
|
post:
|
|
summary: Revoke Agent
|
|
description: Revokes an agent's access by invalidating their JWT (owners only).
|
|
security:
|
|
- sessionAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
agent_id:
|
|
type: string
|
|
required:
|
|
- agent_id
|
|
encoding:
|
|
agent_id:
|
|
contentType: text/plain
|
|
responses:
|
|
'302':
|
|
description: Redirects to the namespace management page
|
|
headers:
|
|
Location:
|
|
description: URL of the namespace management page
|
|
schema:
|
|
type: string
|
|
'400':
|
|
description: Bad Request (e.g., agent ID missing)
|
|
'403':
|
|
description: Forbidden (not owner or not logged in)
|
|
'404':
|
|
description: Namespace or agent not found
|
|
|
|
/namespace/{namespace_short_id}/logs:
|
|
get:
|
|
summary: View Namespace Logs
|
|
description: |
|
|
Displays logs for the specified namespace.
|
|
- **Public Namespaces:** Accessible to all users, including guests.
|
|
- **Private Namespaces:** Requires authentication and at least 'reader' role.
|
|
security:
|
|
- {} # Allows public access to this endpoint
|
|
- sessionAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: namespace_short_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The short ID of the namespace
|
|
- in: query
|
|
name: q
|
|
schema:
|
|
type: string
|
|
description: Search query to filter logs
|
|
responses:
|
|
'200':
|
|
description: Logs page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Forbidden (user does not have access to private namespace)
|
|
'404':
|
|
description: Namespace not found
|
|
|
|
/webhook:
|
|
post:
|
|
summary: Submit Log Entry
|
|
description: Allows agents to submit log entries via JWT authentication.
|
|
security:
|
|
- agentAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
description: The log message
|
|
level:
|
|
type: string
|
|
description: Log level (e.g., INFO, ERROR)
|
|
default: INFO
|
|
metadata:
|
|
type: object
|
|
description: Additional metadata for the log entry
|
|
required:
|
|
- message
|
|
responses:
|
|
'201':
|
|
description: Log entry created
|
|
'400':
|
|
description: Bad Request (e.g., message missing)
|
|
'401':
|
|
description: Unauthorized (missing or invalid JWT)
|
|
'404':
|
|
description: Namespace or agent not found
|
|
|
|
components:
|
|
securitySchemes:
|
|
sessionAuth:
|
|
type: apiKey
|
|
in: cookie
|
|
name: session
|
|
description: Session cookie for authenticated users
|
|
agentAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: JWT authentication for agents
|