Integrate/Authentication

Authentication

All integration paths start with the same auth as ether-app. There is one OTP login flow; your harness or automation uses the returned bearer token on every API call.

OTP flow

Step	Method	Path
Request code	POST	/api/auth/otp/request
Verify code	POST	/api/auth/otp/verify

Verify response includes:

• access_token (or interim token in some environments) — send as Authorization: Bearer …
• user_id — owner scope for tasks and context
• onboarding — ignore for harness-only integrations if the user is already onboarded

Full strategy: ether-core docs/auth-strategy.md.

Using the token

Authorization: Bearer eyJ...
Content-Type: application/json

Harness routes also send:

X-Ether-Harness-App: my-harness

WebSocket auth

Browsers cannot set Authorization on the WebSocket upgrade. Pass the token as a query parameter:

GET /api/realtime?token={url_encoded_access_token}

Then subscribe:

{ "action": "subscribe", "topics": ["tasks/task_abc123"] }

Service vs user tokens

Pattern	Use when
User JWT	Harness runs on behalf of a logged-in user (typical for Ether Code local)
Automation user	Dedicated Ether account for CI; same OTP or future service token

Service-account tokens are not a separate public API yet — use a dedicated user for server automations until documented otherwise.

Local development

When running ether-api locally with LUMA_AUTH_DISABLED=1, use Authorization: Bearer test in curl and tests.

Security notes

• Do not commit tokens or .env files with secrets.
• Optional harness gate: set ETHER_HARNESS_APP_KEY on the API and match it with X-Ether-Harness-App.
• Rotate tokens if leaked; re-verify via OTP.