...

GET /sso-api/site HTTP/1.1
Authorization: Bearer 55d46612-3592-434a-89b2-27c2d66484b7

Scope discovery

https://tools.ietf.org/html/rfc6750#section-3

...

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="8ec15499-2597-4bf1-910d-0b8ea0d396ba" scope="openid 8ec15499-2597-4bf1-910d-0b8ea0d396ba"

Types

Types refer to objects, entities and other resources that are manageable with the API. Common resource types are for example site, group and application. In this document resource types are categorized as follows

• Services
  
  • Connections to user repositories such as SQL and Active Directory
  • Definitions for REST service integrations
  • Session Storage
• Inbound integrations
  • Authentication methods and inbound trust 
  • Directory and service user mapping
  • Attribute mapping
• Application integrations
  • Sites or containers for organizing resources
  • User, group and application
  • Policy definitions for authorization, refresh tokens, persistent id mapping etc

See Management user interface - SSO for information on manageable objects and entities.

Management API Services - SSO

• services
• directory
• service
• sessionStore

Management API inbound integrations - SSO

• server
  • inboundMappingPolicy
    • inboundDirectoryMapping
    • inboundServiceMapping
  • inboundPolicy
    • inboundPolicyItem
  • method

Application integration

...

• /site/System
• /application/System/Ubilogin

Links

Links between resources are used to enable functionality and create integrations. A resource identifier with a path segment "$link" defines a link.

• /application/System/Ubilogin/$link/allowedTo/group/System/Administrators
  • here two resources are connected with a named accessTo link 
• /application/Example/client/$link/policy/Example/policy1
  • here two resources are connected with a typed link

Links between two resources are symmetric

• /group/System/Administrators/$link/accessTo/application/System/Ubilogin
  
  • represents the same link as accessTo link above, but from opposite direction

By leaving out the identifying part from the link target it is possible to navigate the Management API namespace

• /site/$link/one
  • list of all immediate child objects of the root site
• /application/System/Ubilogin/$link/allowedTo
  • list of all groups that are allowed access to Ubilogin application

Attributes

A path segment "$attribute" is used to address special attributes and functionalities of some resource types.

• /application/System/Ubilogin/$attribute/metadata
  • identifies metadata of Ubilogin application

Escaping special characters

...

• /site/System/$$link
  • identifies "$link" sub-site of System site

Operations

The following standard HTTP methods are used for API operations. 

GET

Read resources and links.

GET /site/System
GET /application/System/Ubilogin

GET /site/$link/one
GET /site/System/$link/sub

PUT

Create or update resources and links. The response body contains the newly created or updated resource.

PUT /site/Example
PUT /group/Example/users
PUT /application/Example/client
PUT /application/Example/client/$link/allowedTo/group/Example/users

POST

Create resources and links.

POST /site
	type=site&name=Example
POST /site/Example
	type=group&name=users
POST /site/Example
	type=application&name=client

POST /group/Example/users/$link/policy/Example/policy
	attributename=role&attributevalue=users

DELETE

Delete resources and links.

DELETE /application/Example/client/$link/allowedTo/group/Example/users
DELETE /application/Example/client
DELETE /group/Example/users
DELETE /site/Example

HTTP Status Codes

• 200 OK
  • Operation was successful
• 201 Created
  • Operation was successful
  • Example: in response to creating resources with POST
• 204 No Content
  • Operation was successful, but there was an empty response
  • Example: in response to deleting resources with DELETE
• 400 Bad Request
  • Operation failed because of invalid or missing parameters
  • Example: a required attribute was missing when creating a resource
• 401 Unauthorized
  • The access token is missing or invalid
  • See 1583710248
• 405 Method Not Allowed
  • Resource exists but the HTTP method is not supported
  • Example: attempt to update or remove read-only resource
• 409 Conflict
  • Resource exists but operation failed because of system constraints
  • Example: attempt to overwrite existing resource
• 501 Not Implemented
  • Resource exists but the HTTP method is not implemented
• 503 Service Unavailable
  • The system is unable to handle the request, likely caused by issues on the server side such as maintenance work

Schema

Input to the system is HTML form encoded name value pairs (application/x-www-form-urlencoded).

Output from the system is either XML (application/xml) or JSON (application/json) serialization format. The client uses the Accept request header to choose format. Default format is XML.

XML

Representation

• all values as string values
• single-value attributes as "value" attribute 
• multi-value attributes as nested "value" elements 

<object id="/site/System/SSO%20API" type="site">
    <attribute value="SSO API" name="name" />
    <attribute name="description">
        <value>SSO Management API</value>
    </attribute>
</object>

...