Authentication

POST /auth/signup

Create a new account with an organization.

Body:

{
  "email": "user@example.com",
  "username": "janedoe",
  "first_name": "Jane",
  "last_name": "Doe",
  "password": "securepassword",
  "action": "create",
  "orgCreateProps": {
    "name": "Acme Inc",
    "slug": "acme-inc",
    "description": "Optional description"
  }
}

To join an existing org, use "action": "join" with "invitationCode": "..." instead of orgCreateProps.

POST /auth/signin

Sign in with email and password. Returns JWT tokens.

Body:

{
  "email": "user@example.com",
  "password": "securepassword"
}

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ..."
}

POST /auth/google

Sign in or sign up with a Google OAuth authorization code.

Body:

{
  "code": "4/0Aci..."
}

Response: Same as signin. May include "needsOrg": true if the user has no organization.

POST /auth/setup-org

Set up an organization after Google signup. Requires Bearer token.

Body:

{
  "action": "create",
  "orgCreateProps": {
    "name": "Acme Inc",
    "slug": "acme-inc"
  }
}

POST /auth/refresh

Refresh an expired access token.

Body:

{
  "refresh_token": "eyJ..."
}

POST /auth/iot-credentials

Issue short-lived credentials for connecting to AxonPush realtime over MQTT-over-WSS (AWS IoT Core, custom JWT authorizer).

The Python and TypeScript SDKs call this endpoint internally from connect_realtime() / connectRealtime() and refresh ~60s before expiresAt. You only call it directly if you’re building a non-SDK client.

Auth: Bearer JWT or X-API-Key + X-Tenant-Id.

Body: none.

Response:

{
  "endpoint": "abc123-ats.iot.us-east-1.amazonaws.com",
  "presignedWssUrl": "wss://abc123-ats.iot.us-east-1.amazonaws.com/mqtt?x-amz-customauthorizer-name=axonpush-jwt-authorizer",
  "expiresAt": "2026-05-03T12:34:56.000Z",
  "topicPrefix": "axonpush/org_123",
  "envSlug": "default",
  "topicTemplate": "axonpush/org_123/{envSlug}/{appId}/{channelId}/{eventType}/{agentId}",
  "clientId": "u-abc123-uuid",
  "region": "us-east-1",
  "authorizerName": "axonpush-jwt-authorizer",
  "authToken": "eyJ..."
}

Connect flow:

1. Open a WebSocket to presignedWssUrl with the subprotocol mqttv5.0.
2. Send an MQTT v5 CONNECT packet whose username is authToken and password is empty. AWS IoT routes the CONNECT to the named custom authorizer Lambda, which validates the JWT and returns an IAM policy scoped to topicPrefix.
3. Subscribe to topics under topicPrefix/... using topicTemplate as the layout.
4. Refresh by re-calling this endpoint before expiresAt.

Migration note: Pre-axonpush==0.0.11 (Python) and pre-@axonpush/sdk@0.0.6 (TypeScript) issued a SigV4-signed presigned URL that authenticated the connection on its own. That flow has been retired. The new flow uses an unsigned URL (only ?x-amz-customauthorizer-name=NAME) plus the JWT in the MQTT CONNECT username — authorizerName and authToken are now part of the response.