Skip to content

Organizations

Update an organization

PUT /organizations/{orgId}

Code samples

curl -X PUT https://localhost:9543/api-portal/api/v0.9/organizations/{orgId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Updates organization metadata, claim mappings, role mappings, and portal configuration. orgId must name this instance's own organization; any other returns 403. The id (handle) and idpRefId fields cannot be changed — they are what page URLs and incoming token organization claims are matched against, so a rename would leave the running instance unable to find its own organization. Sending a different value returns 400.

Payload

{
  "displayName": "Acme Corporation",
  "businessOwner": "string",
  "businessOwnerContact": "string",
  "businessOwnerEmail": "[email protected]",
  "id": "acme",
  "idpRefId": "string",
  "cpRefId": "string",
  "configuration": {}
}

displayName: Acme Corporation
businessOwner: string
businessOwnerContact: string
businessOwnerEmail: [email protected]
id: acme
idpRefId: string
cpRefId: string
configuration: {}

Authentication

Parameters

Name In Type Required Description
body body OrganizationUpdateRequest true Organization update payload. Send JSON or an organization YAML file in the organization multipart field. The JSON example below applies only to the application/json content type. When an organization YAML file is uploaded instead, its content must use kind: Organization with the nested shape metadata.name (handle, any top-level id is ignored) and spec.displayName; all other fields (including cpRefId) are read from spec. The YAML spec block additionally accepts labels (upserted by name) and views (upserted by id, which becomes the view's handle, with labels replacing the view's label set) — these are not available via the application/json content type.
orgId path string true The organization's handle (also matches by name or IDP reference ID). Not the internal database uuid.

Example responses

200 Response

{
  "id": "acme",
  "displayName": "Acme Corporation",
  "businessOwner": "string",
  "businessOwnerContact": "string",
  "businessOwnerEmail": "[email protected]",
  "idpRefId": "string",
  "cpRefId": "string",
  "configuration": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "Forbidden"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status Meaning Description Schema
200 OK Organization DTO returned by create, update, and lookup operations. OrganizationResponse
400 Bad Request Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object. Inline
403 Forbidden Request is forbidden. The caller lacks the required permission, or the current runtime mode disallows the operation (read-only mode). It is also returned when the request names an organization other than the single one this instance serves. A nonexistent organization is answered identically to one belonging to someone else, so the response cannot be used to discover what a shared database holds. ErrorResponse
404 Not Found Resource not found. ErrorResponse
409 Conflict The request conflicts with an existing resource. ErrorResponse
500 Internal Server Error Internal server error. ErrorResponse

Response schema

Enumerated Values

Property Value
status error

Get an organization

GET /organizations/{orgId}

Code samples

curl -X GET https://localhost:9543/api-portal/api/v0.9/organizations/{orgId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Retrieves this instance's organization by organization name, handle, or identity provider (IDP) reference ID. Because the portal serves a single organization, orgId must resolve to that one; any other organization returns 403 — and so does an organization that does not exist, so the response cannot be used to discover which organizations the shared database holds.

Authentication

Parameters

Name In Type Required Description
orgId path string true The organization's handle (also matches by name or IDP reference ID). Not the internal database uuid.

Example responses

200 Response

{
  "id": "acme",
  "displayName": "Acme Corporation",
  "businessOwner": "string",
  "businessOwnerContact": "string",
  "businessOwnerEmail": "[email protected]",
  "idpRefId": "string",
  "cpRefId": "string",
  "configuration": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "Forbidden"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status Meaning Description Schema
200 OK Organization DTO returned by create, update, and lookup operations. OrganizationResponse
403 Forbidden Request is forbidden. The caller lacks the required permission, or the current runtime mode disallows the operation (read-only mode). It is also returned when the request names an organization other than the single one this instance serves. A nonexistent organization is answered identically to one belonging to someone else, so the response cannot be used to discover what a shared database holds. ErrorResponse
500 Internal Server Error Internal server error. ErrorResponse