Organizations
The top level of the Organization → Environment → ChargingStation hierarchy (see docs/architecture/tenancy.md) — create, rename, and look up organizations.
5 endpoints
Lists the organizations the caller belongs to, paginated.
get/v1/organizationsRequires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| page | query | integer<int32> | 1-indexed page number. Defaults to 1. |
| per_page | query | integer<int32> | Organizations per page, capped at 100. Defaults to 20. |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | ListOrganizationsResponse | A page of the organizations the caller belongs to |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
Creates an organization, its default "prod" environment, and makes the caller its Owner.
post/v1/organizationsRequires a bearer token
See db::organizations::create — this is the only way an
organization comes into being with a member at all, since there's no
invite flow yet (see docs/architecture/tenancy.md).
Request bodyCreateOrganizationRequest
| Field | Type | Description |
|---|---|---|
| name* | string | — |
| slug* | string | Caller-supplied rather than derived from name (see
migrations/0017_organizations_slug.sql for its format rules). |
Responses
| Status | Body | Description |
|---|---|---|
| 201 | OrganizationSummary | The newly created organization, with the caller as its Owner |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 409 | ErrorBody | An organization with this slug already exists |
Fetches a single organization the caller belongs to, by id.
get/v1/organizations/{organization_id}Requires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| organization_id* | path | string<uuid> | Organization id |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | OrganizationSummary | The organization |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 404 | ErrorBody | No organization with this id exists, or the caller is not a member of it |
Renames and/or re-slugs an organization.
patch/v1/organizations/{organization_id}Requires a bearer token
Requires the caller to be an Owner or Admin of the organization — renaming/re-slugging is an organization-settings action, the same bucket as environment management in docs/architecture/tenancy.md's proposed permission table.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| organization_id* | path | string<uuid> | Organization id |
Request bodyUpdateOrganizationRequest
| Field | Type | Description |
|---|---|---|
| name* | string | — |
| slug | string | null | If present, also changes the organization's slug (see
migrations/0017_organizations_slug.sql for its format rules). |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | OrganizationSummary | The updated organization |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 403 | ErrorBody | The caller is a member but not an Owner or Admin |
| 404 | ErrorBody | No organization with this id exists, or the caller is not a member of it |
| 409 | ErrorBody | An organization with this slug already exists |
Fetches a single organization the caller belongs to, by slug.
get/v1/organizations/by-slug/{slug}Requires a bearer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| slug* | path | string | Organization slug |
Responses
| Status | Body | Description |
|---|---|---|
| 200 | OrganizationSummary | The organization |
| 401 | ErrorBody | Missing, invalid, or expired bearer token |
| 404 | ErrorBody | No organization with this slug exists, or the caller is not a member of it |