Application API

Quick Start

Get up and running in 3 steps:

1. Initialize

Call init to get session

2. Authenticate

Use session ID in requests

3. Call Actions

Login, fetch data, manage state

Endpoint

Base URL: https://proudlyauthentication.com/api/v1 (GET, POST)

All requests can use either:

Route Format: ?route={admin}/{app}/{action}
Form/JSON Format: POST with form data or JSON body

Core Concepts

Handshake Flow

The API uses a handshake pattern for session management:

Client calls init → receives session_id and secret
Client uses session_id in subsequent requests
Optional: C++ clients encrypt requests using the returned secret

Init Handshake

curl -s "https://proudlyauthentication.com/api/v1?route={admin_id}/{app_id}/init"

# Response:
# {
#   "success": true,
#   "session_id": "abc123xyz...",
#   "secret": "secret_key..."
# }

Supported Actions

The API supports the following actions. Route example: /api/v1?route={admin}/{app}/ACTION_NAME

init
Handshake

login
Authenticate

register
New customer

beat
Heartbeat

getsubscriptions
User subs

getuservariable
Get variable

setuservariable
Set variable

downloadfile
File proxy

chatget
Chat history

chatsend
Send message

getprofilepicture
Profile pic

ban
Self ban

Common Parameters

sessionid	Handshake session from `init`. Required for authenticated actions.
action	Action to perform. Use with route format or as parameter.
varid	Variable ID or name (for `getuservariable` / `setuservariable`)
fileid	File ID from application's file proxies (for `downloadfile`)
channel	Chat channel name (for `chatget` / `chatsend`)
message	Message text to send (for `chatsend`)
target_username	Username to look up (for profile picture, user lookup, etc.)

Examples

Login with Session

POST with Form Data

curl -s -X POST "https://proudlyauthentication.com/api/v1" \
  -d "route={admin}/{app}/login" \
  -d "sessionid={session_id}" \
  -d "username=alice" \
  -d "password=secret123"

Get User Variables

JSON POST

curl -s -X POST "https://proudlyauthentication.com/api/v1" \
  -H "Content-Type: application/json" \
  -d '{
    "route": "{admin}/{app}/getuservariable",
    "sessionid": "{session_id}",
    "varid": "user_level"
  }'

Download File

File Download with File ID

curl -s -X POST "https://proudlyauthentication.com/api/v1" \
  -d "route={admin}/{app}/downloadfile" \
  -d "sessionid={session_id}" \
  -d "fileid=your_file_id_here" \
  -o downloaded_file.zip

Python Quickstart

requests library

import requests

BASE = "https://proudlyauthentication.com/api/v1"

# 1. Init
resp = requests.get(BASE, params={"route": "{admin}/{app}/init"})
session_id = resp.json()["session_id"]
print(f"Session: {session_id}")

# 2. Login
resp = requests.post(BASE, data={
    "route": "{admin}/{app}/login",
    "sessionid": session_id,
    "username": "alice",
    "password": "secret"
})
print(resp.json())

# 3. Get subscriptions
resp = requests.post(BASE, data={
    "route": "{admin}/{app}/getsubscriptions",
    "sessionid": session_id
})
print(resp.json())

Security

Per-Session Encryption: By default, the API returns a secret in the handshake that native clients can use for request encryption.

Legacy Key (Deprecated): An optional APPLICATION_LEGACY_ENCRYPTION_KEY env var exists for backwards compatibility, but application-specific keys are recommended.

All sensitive operations validate session state and enforce proper authentication before responding.

Troubleshooting

Error: missing_route

Ensure the route parameter is present and in the format admin/app/action.

Error: session_not_authenticated

The session exists but is not authenticated. Call login or use a valid session ID.

Server Connection Failed

Verify your server is running at localhost:5000. Check Flask logs for details.