Fetching organisations via the API

The API provides methods to query the organisational structure for a domain. This allows a client to obtain information about a given organisation, and also perform operations on accounts that belong to the organisation.

Fetching an organisation

Prerequisites

To fetch an organisation, a client application must

authenticate to the API as described in Authenticating to the API.
obtain a link to an organisation by following a link from a domain, an account object, or by querying an organisation as outlined below.

Procedure

To view information about an organisation, perform a GET request to an organisation resource. To find the resource for the organisation to which the current session belongs, follow the link with a relation of ‘organisation:root’ from the entry-point resource. This will be a URL of the form:

/api/v1/example.org/organisation/<id>

This request returns an application/vnd.eduserv.iam.admin.organisation-v1+json object.

Example

TEXT

Request:
GET /api/v1/example.org/organisation/12345 HTTP/1.1
Authorization: OAApiKey <api-key>
Response (success):
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.organisation-v1+json
 
{
    "id" : "12345",
    "name" : "org 1",
 	"administrators" : [ {
    	"id" : "a0f38436-f490-4c42-ab4d-ddc20c8c181a",
    	"href" : "https://admin.openathens.net/api/v1/example.org/account/a0f38436-f490-4c42-ab4d-ddc20c8c181a",
    	"name" : "exampleusername"
  		}, {
    	"id" : "0e04ed1d-43be-4d52-b3af-86428fcf4446",
    	"href" : "https://admin.openathens.net/api/v1/exampe.org/account/0e04ed1d-43be-4d52-b3af-86428fcf4446",
    	"name" : "exacto"
  		} ],
  	"creationProperties" : {
    "prefix" : "exa",
    "publicId" : false,
    "publicScope" : true,
    "entityids" : {
      "oaFed" : "http://idp.example.org/entity",
      "ukFed" : "http://idp.example.org/entity"
    },
    "scope" : "example.org"
  },
  "contactDetails" : {
    "name" : "Rupert Giles",
    "phone" : "555-1234",
    "emailAddress" : "ripper@example.org",
    "url" : "https://library.example.org"
  },
    "ipRanges" : [ "208.80.152.2" ],
    "attributes" : { "alternativeNames" : [ "Alternative name" ],
                     "emailDomains" : [ "example.com", "example.org" ],
                     "ipRanges" : [ "*.example.com", "*.example.org" ]
    },
    "links" : [
               {
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035",
			    "rel" : "self",
			    "type" : "application/vnd.eduserv.iam.admin.organisation-v1+json",
			    "method" : "get"
			  }, {
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/modify",
			    "rel" : "update",
			    "type" : "application/vnd.eduserv.iam.admin.organisationRequest-v1+json",
			    "method" : "post"
			  }, {
			    "id" : "70001409",
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/70001409",
 			   "rel" : "up",
 			   "type" : "application/vnd.eduserv.iam.admin.organisation-v1+json",
    			"method" : "get",
  			  "name" : "current staff"
 			 }, {
 			   "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/groups",
 			   "rel" : "down",
 			   "type" : "application/vnd.eduserv.iam.admin.groupList-v1+json",
 			   "method" : "get"
			  }, {
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/permission-sets",
			    "rel" : "down",
 			   "type" : "application/vnd.eduserv.iam.admin.permissionSetList-v1+json",
			    "method" : "get"
			  }, {
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/query",
			    "rel" : "organisation:query",
			    "type" : "application/vnd.eduserv.iam.admin.organisationList-v1+json",
			    "method" : "get"
 			 }, {
 			   "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/account-search",
 			   "rel" : "account:search",
			    "type" : "application/vnd.eduserv.iam.admin.accountList-v1+json",
			    "method" : "post"
 			 }, {
 			   "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/accounts/create/personal",
			    "rel" : "add",
			    "type" : "application/vnd.eduserv.iam.admin.accountRequest-v1+json",
			    "method" : "post"
 			 }, {
 			   "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/accounts/create/access",
			    "rel" : "add",
			    "type" : "application/vnd.eduserv.iam.admin.accountRequest-v1+json",
			    "method" : "post"
			  }, {
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/accounts/create/administrator",
			    "rel" : "add",
			    "type" : "application/vnd.eduserv.iam.admin.accountRequest-v1+json",
			    "method" : "post"
			  }, {
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/groups/create",
			    "rel" : "add",
			    "type" : "application/vnd.eduserv.iam.admin.groupRequest-v1+json",
 			   "method" : "post"
			  }, {
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/audit",
			    "rel" : "down",
			    "type" : "application/vnd.eduserv.iam.admin.auditEventList-v1+json",
			    "method" : "get"
			  }, {
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/audit/summary",
			    "rel" : "down",
			    "type" : "application/vnd.eduserv.iam.admin.auditSummaryList-v1+json",
			    "method" : "get"
 			 }, {
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/email-templates",
			    "rel" : "down",
			    "type" : "application/vnd.eduserv.iam.admin.emailTemplateList-v1+json",
			    "method" : "get"
			  }, {
 			   "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/notifications",
 			   "rel" : "down",
 			   "type" : "application/vnd.eduserv.iam.admin.notificationList-v1+json",
			    "method" : "get"
			  }, {
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/notifications/preferences",
			    "rel" : "down",
			    "type" : "application/vnd.eduserv.iam.admin.notificationPreferences-v1+json",
			    "method" : "get"
			  }, {
 			   "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/files",
 			   "rel" : "down",
			    "type" : "application/vnd.eduserv.iam.admin.fileList-v1+json",
			    "method" : "get"
			  }, {
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/resource-catalogue",
 			   "rel" : "down",
			    "type" : "application/vnd.eduserv.iam.resourceList-v1+json",
			    "method" : "get"
			  }, {
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/resource/custom/create",
			    "rel" : "add",
			    "type" : "application/vnd.eduserv.iam.resourceInfo-v1+json",
			    "method" : "post"
 			 }, {
			    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/8291035/api-keys",
			    "rel" : "down",
			    "type" : "application/vnd.eduserv.iam.apiKeyList-v1+json",
			    "method" : "get"
			  } ]
    ]
}

Response codes

HTTP Response Code	Description
200	The request was successful.
400	The request was invalid.
404	The organisation does not exist.

application/vnd.eduserv.iam.admin.organisation-v1+json object

Object field	Description
name	The display name of the organisation.
ipRanges	A list of IP address ranges from which administration of the organisation is restricted.
attributes	A list of attributes relating to the organisation. The attributes returned are defined in the organisation schema.
creationProperties	The prefix, and boolians for a publicId (depreciated) and public scope (identifies users as, e.g. 4567.example.org instead of example.org)
administrators	An array of administrators for the organisation
contactDetails	An array containing a minimum of an email address for contacting the organisation. Can also contain a name, telephone and web address.
entityIds	Any entityIDs specific to the organisation. WIll always be the same as the domain organisation.

Querying organisations

Within the OpenAthens system, organisations are arranged in a hierarchy, as outlined in section 3.4. The API provides a means to query this hierarchical structure by providing access to a list of sub-organisations beneath a known parent organisation.

List sub-organisations

Prerequisites

To query for organisations, a client application must

authenticate to the API as described in Authenticating to the API.
obtain a parent organisation object, as described above.

Procedure

To query for sub-organisations under the control of a particular parent organisation, follow the link with a relation of ‘organisation:query’ from the entry-point resource, or from a parent organisation object. Perform a GET request to:

/api/v1/example.org/organisation/<id>/query

The depth of the query can be controlled via the querystring (see below). The returned data is a flat (non-hierarchical) list of sub-organisations. This can be used by a self-registration interface to cache a type-ahead search for organisation names, without concern for the account hierarchy.

Request querystring

The request can be modified by adding the following querystring parameters to the URL:

Querystring Parameter	Description
attributes	A list of additional attributes to return as part of the result. This avoids a client having to make many additional requests to query attributes for an individual organisation if additional metadata is required at the time the list is generated. If more than one attribute is required, multiple parameters may be added (see example, below).
depth	The depth of sub-organisations to search. A depth of 1 (the default) will list organisations directly under the organization being queried. A depth of -1 will search all levels.
filter	An additional filter to apply to results. The result-list will only contain organisations where the organisation name or the values of any requested attributes contains the filter value supplied by this parameter. The filter is matched case-insensitively.
includeAll	By default only organisations with a unique public identifier assigned to them will be returned by the query. Setting this to ‘true’ will include all organisations, whether public or not. Defaults to ‘false’.

Example

TEXT

Request:
GET /api/v1/example.org/organisation/12345/query?attributes=alternativeName&attributes=emailDomain&depth=1 HTTP/1.1
Authorization: OAApiKey <api-key>
Response (success):
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.organisationList-v1+json
 
{
  "organisations": [
                     { "id" : "4567",
                       "href" : "/api/v1/example.org/organisation/4567",
                       "name" : "org 1", 
					   "href" : "   "https://admin.openathens.net/api/v1/example.org/organisation/4567" 
                       "attributes": {
                         "parentName" : "Groovy Example",
						 "parentId" : "12345"
                       }
                     },
                     { "id" : "7654",
                       "href" : "/api/v1/example.org/organisation/7654",
                       "name" : "org 2"
                     }
  ],
  "links" : [ {
    "href" : "https://admin.openathens.net/api/v1/example.org/organisation/12345",
    "rel" : "up",
    "type" : "application/vnd.eduserv.iam.admin.organisation-v1+json",
    "method" : "get"
  } ]
}

List available permission sets for an organisation

Prerequisites

To list the permission sets belonging to an organisation, a client application must

authenticate to the API as described in Authenticating to the API.
obtain a parent organisation object, as described above.

Procedure

To list the permission sets of a particular parent organisation, follow the link with a relation of ‘organisation:permission-sets’ from the entry-point resource, or from a parent organisation object.

Perform a GET request to:

/api/v1/example.org/organisation/<id>/permission-sets

Request querystring

The request can be modified by adding the following querystring parameter to the URL:

Querystring Parameter	Description
includeCounts	Setting this to ‘true’ will fetch the number of allocated users and number of allocated resources for each permission set. Defaults to ‘false’.

Example

TEXT

Request:
GET /api/v1/example.org/organisation/12345/permission-sets?includeCounts=true HTTP/1.1
Authorization: OAApiKey <api-key>
Response (success):
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.admin.permissionSetList-v1+json
 
{
"total": 2,
    "number": 0,
    "offset": 0,
    "permissionSets": [
        {
            "id": "12345",
            "name": "ath#pset001",
            "description": "Default permission set",
            "attributes": {},
            "created": "2015-03-03T12:49:00Z",
            "modified": "2015-08-19T10:38:00Z",
            "numberOfAllocatedUsers": 32,
            "numberOfAllocatedResources": 15,
            "default": true
        },
        {
            "id": "24680",
            "name": "ath#pset002",
            "description": "Another permission set",
            "attributes": {},
            "created": "2011-10-19T13:40:00Z",
            "modified": "2015-08-04T16:00:00Z",
            "numberOfAllocatedUsers": 5,
            "numberOfAllocatedResources": 2,
            "default": false
        }
 
}