Account and Onboarding

This guide walks you through every step from zero access to a fully provisioned AxiomDB workspace with a connected application. By the end, you will have an organization, a project, a protected main branch, your device allowlisted, and a running Prisma migration.

Prerequisites

Before you begin, ensure you have:

Step 1 — Sign up through Square IdP

AxiomDB delegates authentication to Square IdP, your organization's centralized identity provider. This means you don't create a separate AxiomDB password — your identity is managed through OAuth2/OIDC with PASETO v4 tokens.

Web console sign-up

1. Navigate to the Ops Console at https://axiomdb.squareexp.com.
2. Click Sign in with Square.
3. You'll be redirected to the Square IdP authorization endpoint.
4. Authenticate with your organizational credentials.
5. Upon successful authentication, the IdP redirects back with an authorization code.
6. The gateway exchanges the code for tokens and creates your user record.
7. You land on the Projects page — your workspace is ready.

CLI sign-up

The CLI uses a browser-based OAuth2 PKCE flow that doesn't require a client secret:

npm install -g axiomdb-cli
axm login

The CLI will:

1. Generate a PKCE code verifier and challenge.
2. Open your browser to the Square IdP authorization endpoint.
3. Start a local loopback server to receive the callback.
4. Display a prompt: Complete sign-in in browser...
5. After authentication, the browser redirects to the loopback with an authorization code.
6. The CLI exchanges the code for tokens and stores the session locally.
7. If the browser callback doesn't complete, you can paste the authorization code or full redirect URL manually.

Verifying your session

After signing in, verify your identity:

axm whoami

This returns your user ID, email, organization membership, and active role.

Step 2 — Create your organization

When you first sign in, AxiomDB creates or links your user record to an organization. Organizations are the top-level workspace that owns projects, team membership, billing, and audit events.

Organization fields

Inviting team members

Organization owners and admins can invite team members through the console or CLI:

# Via console
# Navigate to Settings > Team > Invite Member

# Via API
curl -X POST https://api.axiomdb.squareexp.com/api/v1/organizations/<org-id>/invitations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"email": "teammate@example.com", "role": "developer"}'

Invitations are email-based, expire after 7 days, and can be revoked by any owner or admin. When a teammate accepts, their account is created or linked and the organization membership is established.

Role matrix

Step 3 — Install the CLI

The axm CLI is the fastest path to AxiomDB. It's a Rust binary distributed through npm for cross-platform compatibility.

npm install -g axiomdb-cli

Verify the installation:

axm -h

The package exposes axm as the primary binary. The longer axiom binary remains available for backward compatibility.

CLI architecture

The CLI communicates directly with the AxiomDB Gateway at api.axiomdb.squareexp.com over HTTPS. It stores session tokens locally in ~/.axiomdb/ and supports multiple profile configurations for different environments.

┌──────────────┐     HTTPS      ┌───────────────────┐     Redis      ┌──────────────┐
│   axm CLI    │ ──────────────▶ │  AxiomDB Gateway  │ ──────────────▶│ square-dbctl │
│  (terminal)  │ ◀────────────── │  (Axum + PASETO)  │ ◀──────────────│  (provisioner)│
└──────────────┘    responses    └───────────────────┘    commands    └──────────────┘
       │                               │
       │ local session                 │ control-plane DB
       ▼                               ▼
  ~/.axiomdb/                    PostgreSQL metadata

Step 4 — Create your first project

A project is the top-level workspace that owns branches, team access, network policy, backups, and audit events. It is not a connection target — you connect to branches, not projects.

axm projects create --name "Square Experience" --app-key square_experience --env main

What happens during project creation

The gateway executes a multi-step provisioning pipeline:

1. Metadata creation — Inserts a project row into the control-plane database with status active.
2. Main branch provisioning — Creates a protected main branch with lifespan forever.
3. Database provisioning — Executes CREATE DATABASE sq_<app_key>_<env> via square-dbctl.
4. Role provisioning — Creates three Postgres roles:
   • <app_key>_<env>_owner — Migration role with CREATEDB privilege
   • <app_key>_<env>_rw — Runtime read/write role
   • <app_key>_<env>_ro — Read-only analytics role
5. Credential generation — Generates cryptographically strong passwords and stores them in the encrypted secret file (~/.creds/zone.env).
6. PgBouncer configuration — Adds the runtime role to the PgBouncer userlist.
7. Network initialization — Creates default network policy (restricted mode) with no allowlisted CIDRs.
8. Audit logging — Records project.created and branch.created events with actor, timestamp, and metadata.

Project response

{
  "project": {
    "id": "proj_a1b2c3d4",
    "name": "Square Experience",
    "app_key": "square_experience",
    "env": "main",
    "status": "active"
  },
  "main_branch": {
    "id": "br_e5f6g7h8",
    "branch_name": "main",
    "database_name": "sq_square_experience_main",
    "lifespan": "forever",
    "protected": true,
    "status": "active"
  }
}

Step 5 — Select the project

Set the active project so branch commands don't require the project ID every time:

axm projects list
axm projects use <project-id>

With an active project set, you can use shorter commands:

axm branches list
axm branches urls --name main

Step 6 — Allow your device

AxiomDB defaults to restricted network mode. Your device cannot reach Postgres until you explicitly allow its IP address.

Quick allow via CLI

axm network allow --current

This detects the public IP the gateway sees from your connection and stores it as a /32 CIDR rule for the active project.

Allow via console

1. Navigate to the Network page in the console.
2. Click My IP — the gateway detects and displays your current public IP.
3. Review the generated JSON payload.
4. Click Save JSON — the rule is applied to Postgres, PgBouncer, and UFW.
5. Retry your app or migration command.

Understanding the network payload

{
  "policy": {
    "apply": false,
    "mode": "restricted"
  },
  "rules": [
    {
      "cidr": "203.0.113.10/32",
      "expires_in": "7d",
      "label": "My current IP",
      "ports": "both",
      "scope": "project"
    }
  ]
}

How network rules are applied

When you save a network rule, the gateway:

1. Validates the CIDR format and checks for conflicts.
2. Stores the rule in the network_rules control-plane table.
3. Generates managed configuration blocks for PostgreSQL (pg_hba.conf), PgBouncer, and UFW.
4. Applies the configuration using square-dbctl with managed markers so AxiomDB can update its own sections without touching unrelated VPS configurations.
5. Records a network.rule.created audit event with the actor, IP, user agent, and rule metadata.

Step 7 — Copy branch URLs

With your device allowlisted, fetch the connection URLs for your branch:

axm branches urls --name main

The output is ready to paste into your .env file:

DATABASE_URL="postgresql://square_experience_rw:***@db.squareexp.com:6432/sq_square_experience_main?sslmode=require"
DIRECT_URL="postgresql://square_experience_owner:***@db.squareexp.com:5432/sq_square_experience_main?sslmode=require"

The Connect modal

In the web console, clicking Connect on any branch opens a modal with:

• Pre-formatted .env blocks for Prisma, Drizzle, Kysely, node-postgres, SQLAlchemy, Django, Laravel, Go pgx, and Rust SQLx.
• Copy-to-clipboard buttons for each URL.
• Framework-specific setup instructions.
• A security reminder about credential handling.

Step 8 — Run your first migration

With your .env configured, run your first Prisma migration:

npx prisma migrate dev --name init

Prisma uses DATABASE_URL (port 6432, PgBouncer) for runtime queries and DIRECT_URL (port 5432, direct Postgres) for schema changes, advisory locks, and shadow database creation.

Step 9 — Explore the dashboard

Navigate to your project in the console to explore:

• Branches — View all active, expired, and protected branches with their status, storage usage, and connection counts.
• Tables — Inspect the live schema, browse rows, and use the Schema Flow visualizer.
• Network — Manage allowlist rules, view the current access mode, and audit network changes.
• Backups — Create snapshots, view backup freshness, and restore into new branches.
• Monitoring — Real-time metrics for database size, connections, query load, and migration state.
• Audit — Every sensitive action tracked with actor, timestamp, IP, and metadata.
• Settings — Configure branch cleanup policies, CORS origins, Data API tokens, and team access.

Step 10 — Create your first branch

Branches let you test schema changes without touching the main database:

axm branches create --name feature-auth --source main --lifespan 7d

This provisions a new database (sq_square_experience_main_br_feature-auth), creates independent credentials, and copies the schema from the source branch. The branch has its own connection URLs, its own network grants, and its own audit trail.

Next steps

Troubleshooting

"Connection refused" or "timeout" when connecting

Cause: Your device IP is not allowlisted in the project's network policy.

Fix: Run axm network allow --current or add your IP through the Network page in the console.

"Authentication failed" when connecting to Postgres

Cause: The branch credentials may have been rotated, or you're using expired URLs.

Fix: Run axm branches urls --name <branch-name> to get fresh credentials and update your .env.

"Branch limit exceeded" when creating a branch

Cause: The project has reached the maximum of 10 active branches.

Fix: Delete unused branches with axm branches delete <branch-name> or request a limit extension.

CLI shows "No active project selected"

Cause: You haven't set an active project context.

Fix: Run axm projects list to see available projects, then axm projects use <project-id> to set the active project.