API methods - organisations

An organisation represents a legal entity that users and service accounts act on behalf of. Each organisation has a name and a country of registration. Users and service accounts can be assigned to organisations and the Authorization Server uses these assignments to provide the permitted_organisations attribute for the principal (see How organisations affect access).

An organisation has the following properties:

Property	Description
`id`	A unique identifier generated by the Authorization Server when the organisation is created.
`name`	The name of the organisation. Names must be unique, irrespective of case, so `Telicent` and `TELICENT` cannot both exist.
`countryOfRegistration`	The country in which the organisation is registered, as an ISO 3166-1 alpha-3 country code, for example `GBR` or `USA`. Codes are not case-sensitive in requests and are always stored and returned in upper case.

Organisations can be created through this API or populated when the Authorization Server starts using seed data.

Create an organisation

To access this endpoint you must have organisations.write permission.

POST /organisations

Both name and countryOfRegistration are required.

Request body example:

{
  "name": "Telicent",
  "countryOfRegistration": "GBR"
}

Responses:

Status: 200 - organisation created and returned

Response body example:

{
  "id": "0f2d1c8e-5b3a-4c52-9d0b-7a6f2b1e4c93",
  "name": "Telicent",
  "countryOfRegistration": "GBR"
}

Status: 400 - organisation already exists

{
  "error": "conflict",
  "error_description": "An organisation with this name already exists."
}

Status: 400 - invalid request

Returned if the name is missing or blank, or the country of registration is missing or is not a valid ISO 3166-1 alpha-3 code.

{
  "error": "invalid_request",
  "error_description": "Invalid create organisation request"
}

Status: 403 - insufficient permissions

Delete an organisation

To access this endpoint you must have organisations.write permission.

DELETE /organisations/{organisationId}

Deleting an organisation does not remove it from the users and service accounts that have been assigned to it. Remove the organisation from those users, using the Update user endpoint, before or after deleting it to avoid leaving stale assignments.

Responses:

Status: 204 - organisation deleted

Status: 403 - insufficient permissions

Status: 404 - organisation not found

Get organisation by ID

To access this endpoint you must have organisations.read permission.

GET /organisations/{organisationId}

Responses:

Status: 200 - organisation returned

Response body example:

{
  "id": "0f2d1c8e-5b3a-4c52-9d0b-7a6f2b1e4c93",
  "name": "Telicent",
  "countryOfRegistration": "GBR"
}

Status: 403 - insufficient permissions

Status: 404 - organisation not found

Get organisations

To access this endpoint you must have organisations.read permission.

GET /organisations

The results are paged. The following optional query parameters control the page returned:

Parameter	Description	Default
`page`	The zero-based page number. Must not be negative.	`0`
`size`	The number of organisations in a page. Must be between 1 and 100.	`50`

Responses:

Status: 200 - a page of organisations returned

count is the total number of organisations, not the number in the page.

Response body example:

{
  "count": 2,
  "page": 0,
  "size": 50,
  "totalPages": 1,
  "hasNext": false,
  "organisations": [
    {
      "id": "0f2d1c8e-5b3a-4c52-9d0b-7a6f2b1e4c93",
      "name": "Telicent",
      "countryOfRegistration": "GBR"
    },
    {
      "id": "6b7e0a41-93c4-4f0e-8a2d-1c5e9d3f7a58",
      "name": "Acme Corp",
      "countryOfRegistration": "USA"
    }
  ]
}

Status: 400 - invalid paging parameters

{
  "error": "invalid_request",
  "error_description": "page must be non-negative and size must be between 1 and 100"
}

Status: 403 - insufficient permissions

Update an organisation

To access this endpoint you must have organisations.write permission.

PUT /organisations/{organisationId}

Only the values to be updated need to be sent in the request. Properties that are omitted are left unchanged. The id of an organisation cannot be changed.

Request body example (to rename an organisation):

{
  "name": "Telicent Ltd"
}

Responses:

Status: 200 - organisation updated and returned

Response body example:

{
  "id": "0f2d1c8e-5b3a-4c52-9d0b-7a6f2b1e4c93",
  "name": "Telicent Ltd",
  "countryOfRegistration": "GBR"
}

Status: 400 - invalid request

Returned if the name is blank, the name is already used by another organisation, or the country of registration is not a valid ISO 3166-1 alpha-3 code.

{
  "error": "invalid_request",
  "error_description": "Country of registration \"XYZ\" is not a valid ISO 3166-1 alpha-3 country code"
}

Status: 403 - insufficient permissions

Status: 404 - organisation not found

How organisations affect access

When a user or service account is assigned to one or more organisations, the Authorization Server adds a permitted_organisations attribute to the attributes it returns for that principal from the /userinfo endpoint. Telicent applications use these attributes when making access control decisions.

The attribute is a list containing, for each organisation, the country of registration in the form {COUNTRY}.ALL (for example GBR.ALL), followed by the organisation names. For a user assigned to the Telicent organisation registered in the United Kingdom, the attribute would be:

"permitted_organisations": ["GBR.ALL", "Telicent"]

Changes to an organisation’s name or country of registration are reflected in the attribute the next time the principal’s information is requested. The attribute is omitted if the principal is not assigned to any organisation, and an organisation with no country of registration contributes only its name.

Organisations migrated from earlier versions

Earlier versions of the Authorization Server held the organisation of a user or service account as a free-text deployedOrganisation attribute. When the Authorization Server is upgraded, an organisation is created for each distinct deployedOrganisation value, matched irrespective of case against any organisations that already exist (for example those created from seed data), and each user and service account is assigned to the matching organisation.

The old attribute carried no country, so organisations created by the migration have no countryOfRegistration. Use the Update an organisation endpoint to supply the country for each of these organisations. To avoid this step, define the organisations, with their correct countries, in the seed data before upgrading.