# Simplest1 Platform API

> platform platform API on Simplest1

## Accounts

Account and owner management

- GET /api/v1/accounts/{id} - Get account details (auth required)
  data: {id: string, plan: string, billing_cycle: string, created_at: string, updated_at: string}
- GET /api/v1/accounts/{id}/owners - List account owners (auth required)
  data: list of {email: string, name: string, added_by: string, added_at: string}
- POST /api/v1/accounts/{id}/owners - Add an account owner (auth required)
  body: {email: string, name: string, added_by: string}
- DELETE /api/v1/accounts/{id}/owners/{email} - Remove an account owner (auth required)

## Authentication

Magic link authentication and session management

- POST /api/v1/auth/magic-link - Request a magic link
  body: {email: string (required), tenant_id: string (required)}
  data: {token: string}
- POST /api/v1/auth/verify - Verify a magic link token
  body: {token: string (required)}
  data: {email: string, tenant_id: string}
- GET /api/v1/auth/me - Get current user (auth required)
  data: {id: string, email: string, name: string, created_at: string}

## Domains

Custom domain management and verification

- GET /api/v1/domains - List domains (auth required)
  data: list of {id: string, tenant_id: string, domain: string, status: string, ssl_status: string, verified: boolean, created_at: string, updated_at: string}
- POST /api/v1/domains - Add a custom domain (auth required)
  body: {domain: string (required)}
  data: {id: string, tenant_id: string, domain: string, status: string, ssl_status: string, verified: boolean, created_at: string, updated_at: string}
- GET /api/v1/domains/{id} - Get domain details (auth required)
  data: {id: string, tenant_id: string, domain: string, status: string, ssl_status: string, verified: boolean, created_at: string, updated_at: string}
- POST /api/v1/domains/{id}/verify - Verify domain DNS (auth required)
  data: {domain: string, status: string, ssl_status: string, verified: boolean, dns_target: string, instructions: string, errors: []string}
- DELETE /api/v1/domains/{id} - Remove a domain (auth required)

## Signup

Create an app for someone via API; they receive a one-time code by email, the client hands it back and receives an API key

- POST /api/v1/signup - Create a pending app and email the owner a code
  body: {app: string (required), subdomain: string (required), name: string (required), email: string (required)}
  data: {tenant_id: string, subdomain: string, status: string, code_expires_at: string (date-time), next: string}
- GET /api/v1/signup/{id} - Signup status: pending | active | expired
  data: {status: string, tenant_id: string}
- POST /api/v1/signup/{id}/verify - Submit the code; activates the app and returns an API key
  body: {code: string (required)}
  data: {tenant_id: string, status: string, site_url: string, admin_url: string, api_key: string}
- POST /api/v1/signup/{id}/resend - Send a fresh code
  data: {resent: boolean, status: string}

## Tenants

Tenant lifecycle management

- POST /api/v1/tenants - Create a tenant (auth required)
  body: {subdomain: string (required), app_type: string (required), plan: string, owner_email: string (required), owner_name: string}
  data: {id: string, account_id: string, subdomain: string, app_type: string, plan: string, status: string, created_at: string, updated_at: string}
- GET /api/v1/tenants - List tenants (auth required)
  data: list of {id: string, account_id: string, subdomain: string, app_type: string, plan: string, status: string, created_at: string, updated_at: string}
- GET /api/v1/tenants/{id} - Get tenant details (auth required)
  data: {id: string, account_id: string, subdomain: string, app_type: string, plan: string, status: string, created_at: string, updated_at: string}
- POST /api/v1/tenants/{id}/terminate - Terminate a tenant (auth required)
  body: {terminated_by: string}

## Conventions

JSON in and out; send `Content-Type: application/json` on every write.
Every response is an envelope: `{"ok": true, "data": ..., "meta": {...}}` on success,
`{"ok": false, "error": {"code": "...", "message": "...", "details": [...]}}` on failure.
`body:` above is the request JSON; `data:` is what the envelope's data holds. A `?` after a type means it may be null or absent.
Lists paginate with `?page=1&per_page=20`; `meta` carries `page`, `per_page`, `total_count`, `total_pages`.
The API only ever grows: fields and endpoints are added, never removed or renamed (see /api/openapi.json for schemas).

## Authentication

Endpoints marked (auth required) take an API key or a session.
- Bearer: `Authorization: Bearer sk_live_...`
- Header: `X-API-Key: sk_live_...`

Create keys in the admin under Settings > Integrations > API (/admin/integrations/api), or receive one from the API signup flow.