App Server (Controller)

Last Updated: June 15, 2026

The App Server is the backend service that the SDK talks to. It ensures secure and standardized communication.

https://bitbucket.org/antsdm/careflow-controller-server/src

Authentification Method

All endpoints require HMAC-signed request headers, not Bearer tokens.

Each request must include:

x-app-uuid: <client_id>

x-timestamp: <epoch_ms>

x-signature: <HMAC_SHA256 signature>

The signature is generated using:

canonical = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + SHA256(body)

signature = Base64(HMAC_SHA256(canonical, client_secret))

The Controller Server must:

• Validate timestamp freshness (example: within 5 minutes).
• Recompute the canonical string on the server side.
• Validate the signature using the stored client_secret for that x-app-uuid.

This replaces:

• Bearer token authentication
• /auth/token endpoint requirement

Response Format

All endpoints return consistent JSON:

{
  "status": "success" | "error",
  "data": { ... },
  "error": {
      "code": "INVALID_SIGNATURE",
      "message": "Signature verification failed"
  }
}

Errors should clearly identify:

EXPIRED_TIMESTAMP

INVALID_SIGNATURE

UNKNOWN_APP_ID

FORBIDDEN

BAD_REQUEST

Versioning

All endpoints must be prefixed with: /v1/

This ensures future expansion without breaking compatibility.

App Server API endpoints

1. Deployment Info

App needs to know what it’s working with.

GET /v1/deployment

Get details of the deployment (status, type, endpoints, metadata, control).

• dump YAML? Has all the information
• Topics of this connector,
• Control of all images
• Application -> YAML
  • Topics
    • In/out
• YAML -> models with control topic ->

2. Input/ Output

Where the SDK fetches results or submits new data. (profile secret)

POST /v1/deployment/publish

Submit an input payload

• Topic publish
  • Use HMAC encrypt to publish
    • At server, it will try to find the connector associate with secret

GET /v1/deployment/subscribe

Poll for the latest output

3. Control

Control the behavior of a deployment.

POST /v1/deployment/control

• Similar to publish, but it is for sending control to model images (e.g. thresholds, parameters, target image).
• Find connector, then publish to topic if it is part of YAML

4. Streaming (postponed)

For real-time output.

GET /v1/deployment/stream/url

• Returns a WebSocket URL with an expiring token.
• Response: { "ws_url": "wss://..." }

(Optional) WebSocket messages

• Output events
• Control acks/errors

5. Users

For user list retrieval.

GET /v1/users

• Returns lists of app users with admin role or not

6. Session

For user session validation.

GET /v1/session

• Validation the user session

7. User Login (Optional)

If you want to allow Careflow user accounts (instead of App-only).

GET /v1/auth/redirect

• Redirect endpoint for OAuth-like login with Careflow user.

GET /v1/auth/userinfo

• Returns info about the authenticated Careflow user.

Notes

• All endpoints require HMAC-signed headers: x-app-id, x-timestamp, x-signature.
• Response format: consistent JSON, with status, data, error.
• Version prefix (/v1/) allows future expansion.
• Controller Routing
  • The App defines how incoming SDK or HTTPS requests are routed to the correct deployment topics.
  • Authentication uses HMAC signed requests (App ID + App Secret).
• Session Management
  • Provides session validation for App Users.
  • Allows user identity to attach to App behaviors or UI components.