Skip to main content

Register an Organization

POST/api/registrations
Public

Open /register to create an Organization and its first account, which is an administrator. REST clients call POST /api/registrations with {"organizationName", "displayName", "email", "password", "outputLanguage"} after fetching a CSRF token (see REST API); outputLanguage is optional and defaults to English. An email address belongs to one account across the whole deployment, so registering it twice returns 409 email_already_registered. Registration also seeds the Organization's category catalog, its four preset audiences, and its public changelog address.

Read more: RegistrationSource: RegistrationApiController#register(opens in new tab)

Request body​

application/json

FieldTypeRequiredNotes
organizationNamestringRequiredmax 120
displayNamestringRequiredmax 120
emailstringRequiredemail · max 254
passwordstringRequired
outputLanguagestringOptionalmax 64

Response​

Success: 201

FieldTypeRequiredNotes
organizationIdstring (uuid)Optional
organizationNamestringOptional
userIdstring (uuid)Optional
emailstringOptional
displayNamestringOptional
roleenum AppUserRoleOptionalADMINMEMBER
outputLanguagestringOptional
changelogSlugstringOptional

Errors​

StatusCodeApplies to
400validation_faileda field is missing or out of rangeAny endpoint
400malformed_requestthe body cannot be readAny endpoint
400invalid_parametera path or query parameter is missing or does not convert, such as an ID that is not a UUIDAny endpoint
403access_deniedan administrator endpoint, or a missing or stale CSRF tokenAny endpoint
404not_foundno such addressAny endpoint
405method_not_allowedthe address does not take that methodAny endpoint
415unsupported_media_typethe address does not read a body of that typeAny endpoint
500internal_errora fault ReleaseFlow did not foresee; the body never carries the exception behind itAny endpoint
400output_language_invalidAccount area
400ui_locale_invalidAccount area
400invitation_invalidAccount area
400organization_slug_invalidAccount area
404invitation_not_foundAccount area
404member_not_foundAccount area
409email_already_registeredAccount area
409invitation_already_pendingAccount area
409invitation_email_unavailableAccount area
409organization_slug_takenAccount area
409member_last_administratorAccount area

Request

bash
# CSRF_HEADER and CSRF_TOKEN are the headerName and token GET /api/csrf returned.
curl -X POST "http://localhost:8080/api/registrations" \
-b cookies.txt -c cookies.txt \
-H "$CSRF_HEADER: $CSRF_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"organizationName": "<string>",
"displayName": "<string>",
"email": "<string>",
"password": "<string>",
"outputLanguage": "<string>"
}'

The request body is an example built from the schema; replace every placeholder.

Response

201

Example

{
  "organizationId": "<uuid>",
  "organizationName": "<string>",
  "userId": "<uuid>",
  "email": "<string>",
  "displayName": "<string>",
  "role": "ADMIN",
  "outputLanguage": "<string>",
  "changelogSlug": "<string>"
}