Organizations¶

Create an organization (not supported)¶

POST /organizations

Code samples

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

NOT SUPPORTED. A well-formed request returns 405; a malformed one can still fail validation first with 400, or 415 for an unsupported content type. This API Portal serves the single organization named by its organization.handle configuration, which is created on startup along with its default portal configuration, label, view, and subscription plans. The operation is retained for forward compatibility.

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¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `dp:organization:create`, `dp:organization:manage`

Parameters

Name	In	Type	Required	Description
body	body	OrganizationCreateRequest	true	Organization creation 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` (array of `{name, displayName}`) and `views` (array of `{id, displayName, labels}` — `id` becomes the view's handle) to bootstrap labels and views at creation time — these are not available via the `application/json` content type.

Example responses

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"
}

405 Response

{
  "status": "error",
  "code": "METHOD_NOT_ALLOWED",
  "message": "This API Portal serves a single organization, which is configured and provisioned at startup. Organizations cannot be created, listed, or deleted through the API."
}

415 Response

{
  "status": "error",
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "message": "Content-Type must be application/json."
}

500 Response

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

Responses

Status	Meaning	Description	Schema
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
405	Method Not Allowed	The operation is not offered by this deployment. Returned by the organization lifecycle operations, which an API Portal serving a single organization does not expose — that organization is configured and provisioned at startup.	ErrorResponse
415	Unsupported Media Type	Unsupported request media type.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response schema

Enumerated Values

Property	Value
status	error

List organizations (not supported)¶

GET /organizations

Code samples

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

NOT SUPPORTED. A well-formed request returns 405; a malformed one can still fail validation first with 400. Listing is inherently cross-organization, and this API Portal serves exactly one. Use GET /organizations/{orgId} with this instance's own handle instead. The operation is retained for forward compatibility.

Authentication¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `dp:organization:read`, `dp:organization:manage`

Example responses

405 Response

{
  "status": "error",
  "code": "METHOD_NOT_ALLOWED",
  "message": "This API Portal serves a single organization, which is configured and provisioned at startup. Organizations cannot be created, listed, or deleted through the API."
}

500 Response

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

Responses

Status	Meaning	Description	Schema
405	Method Not Allowed	The operation is not offered by this deployment. Returned by the organization lifecycle operations, which an API Portal serving a single organization does not expose — that organization is configured and provisioned at startup.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Update an organization¶

PUT /organizations/{orgId}

Code samples

curl -X PUT https://localhost:9543/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¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `dp:organization:update`, `dp:organization:manage`

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/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¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `dp:organization:read`, `dp:organization:manage`

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

Delete an organization (not supported)¶

DELETE /organizations/{orgId}

Code samples

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

NOT SUPPORTED. A well-formed request returns 405; a malformed one can still fail validation first with 400. This API Portal instance is bound to a single organization for its whole lifetime; deleting it would leave the instance serving nothing. The operation is retained for forward compatibility.

Authentication¶

This operation requires a Bearer JWT access token in the Authorization header. Required scopes (the token must carry at least one of): `dp:organization:delete`, `dp:organization:manage`

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

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"
}

405 Response

{
  "status": "error",
  "code": "METHOD_NOT_ALLOWED",
  "message": "This API Portal serves a single organization, which is configured and provisioned at startup. Organizations cannot be created, listed, or deleted through the API."
}

500 Response

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

Responses

Status	Meaning	Description	Schema
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
405	Method Not Allowed	The operation is not offered by this deployment. Returned by the organization lifecycle operations, which an API Portal serving a single organization does not expose — that organization is configured and provisioned at startup.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response schema

Enumerated Values

Property	Value
status	error