POST /v1/auth/signup — create a new Axis account

Create a developer or business account. Returns a JWT session token used to authenticate subsequent requests from your frontend.

Use this endpoint to register a new Axis account. Choose "developer" to explore the API with personal credentials, or "business" to unlock wallet creation and agent payment infrastructure. A signed JWT session token is returned immediately on success — store it securely (e.g. in memory or an httpOnly cookie) and attach it to subsequent requests via the Authorization header.

Endpoint

POST /v1/auth/signup

Authentication

None required. This is a public endpoint.

Request Body

email · string · required

A valid email address. Must be unique across all Axis accounts.

password · string · required

The account password. Minimum 6 characters.

accountType · string · required

The type of account to create. Accepted values: "developer" or "business".

businessName · string

The legal or trading name of the business. Required when accountType is "business".

Request Example

{
  "email": "[e-mail]",
  "password": "sup3rS3cur3!",
  "accountType": "business",
  "businessName": "Acme Corp"
}

Response — 201 Created

A successful request returns HTTP 201 with a JSON body containing a JWT session token and the newly created user record. Note that token lives directly inside data, alongside user — it is not nested inside data.user.

status · string

Always "success" for a successful response.

data · object

Container for the session token and user details.

Show data fields

data.token · string

A signed JWT session token. Include this in the Authorization: Bearer <token> header for all authenticated requests.

data.user · object

The newly created user record.

Show user fields

data.user.id · string

Unique UUID for the user account.

data.user.email · string

The email address associated with the account.

data.user.accountType · string

The account type: "developer" or "business".

data.user.businessId · string | null

UUID of the auto-created business entity when accountType is "business". null for developer accounts.

data.user.createdAt · string

ISO 8601 timestamp of when the account was created.

{
  "status": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImU5YjFmMjAzLTQ4NzEtNGUwZS1hNmNkLTFkNzZkYmMxNjNmZiIsImVtYWlsIjoiZGV2QGFjbWUuaW8iLCJpYXQiOjE3NTMwODgwMDAsImV4cCI6MTc1MzE3NDQwMH0.dummysignature",
    "user": {
      "id": "e9b1f203-4871-4e0e-a6cd-1d76dbc163ff",
      "email": "[e-mail]",
      "accountType": "business",
      "businessId": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
      "createdAt": "2026-07-21T09:00:00.000Z"
    }
  }
}

Error Responses

400 — Validation Error

Returned when one or more request fields fail validation. The errors array contains individual Zod issue objects, each identifying the failing field and the reason.

{
  "status": "error",
  "errors": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["email"],
      "message": "Required"
    },
    {
      "code": "too_small",
      "minimum": 6,
      "type": "string",
      "inclusive": true,
      "exact": false,
      "path": ["password"],
      "message": "String must contain at least 6 character(s)"
    },
    {
      "code": "invalid_enum_value",
      "options": ["developer", "business"],
      "path": ["accountType"],
      "message": "Invalid enum value. Expected 'developer' | 'business', received 'admin'"
    }
  ]
}

409 — Email Already Registered

Returned when an account with the supplied email address already exists. Use this response to prompt the user to log in instead.

{
  "status": "fail",
  "message": "User with this email already exists"
}