---
title: "Register a Community SaaS tenant (hosted deployment only)"
method: POST
path: "/api/v1/register"
tags: ["Community SaaS"]
---

# Register a Community SaaS tenant (hosted deployment only)

`POST /api/v1/register`

## Request

- Base URL: `https://agent.getaxonflow.com`
- URL: `https://agent.getaxonflow.com/api/v1/register`
- Auth: none required
- TypeScript: <https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/docs/api/v1/register/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a free-tier tenant on the hosted Community SaaS deployment
and returns its credentials once. Mounted only under
`DEPLOYMENT_MODE=community-saas`; every other deployment answers
404. Not authenticated: it is the bootstrap that creates the
credential every other route needs. Limited to 5 registrations per
client IP per hour.

EVERY FIELD IS OPTIONAL (#4249 row 5764325123). `{}`, an empty body
and no body register an unlabelled tenant with no email; the Go and
Java SDKs' `RegisterTry("")` send exactly `{}`. A field the route
does not know is ignored. Every refusal below is decided before
anything is written, and discloses no credential.

## Request body

- object
  - `label` string: An operator-readable name for the tenant.
  - `email` string, email: Binds the tenant to this address for the free recovery flow (`/api/v1/recover`). At most 3 active tenants per email.
  - `internal_tenant_id_prefix` string: AxonFlow's own internal callers only: one of a fixed allowlist of `axonflow-internal-*` prefixes. Any other value is refused 400.

## Response `201`

The tenant was created; the secret is shown only this once.

- object
  - `tenant_id` string
  - `secret` string
  - `secret_prefix` string
  - `expires_at` string, date-time
  - `endpoint` string
  - `note` string

## Other responses

- `400`: The body is not JSON, or a field is invalid. The message names it: `Invalid JSON in request body`, `Label too long (max 255 characters)`, `Invalid email format`, or `Unsupported internal_tenant_id_prefix value`.
- `405`: GET, PUT, DELETE or PATCH.
- `409`: The email already holds the maximum of 3 active tenants.
- `413`: The body is over 1024 bytes.
- `415`: A Content-Type other than `application/json` (with optional parameters). An absent Content-Type is accepted.
- `429`: More than 5 registrations from this client IP in the hour.
- `500`: The registration could not be created; no credential is returned.
- `503`: The database is not available.

---

[API](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api.md) - [All operations](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/revisions/34d30fcb7fa1?raw)