## Authentication and Hypermedia Links

After the user’s identity has been established by the Authentication process, App Orchestration then determines whether the caller has permission to call the API endpoint they are trying to access. If they are denied access, they will receive a `403 Forbidden` response status code. Otherwise, the results will be returned and/or the actions performed as per the specific API documentation.

App Orchestration uses hypermedia links to enable navigation through the object hierarchy returned from the API.

### Curies

All hypermedia links returned by the App Orchestration API use "curies". "Curie" stands for "compact URI" and is of the format:

       [prefix:resource]

The curie format allows removing lots of redundant information from the API data payload. It represents a common prefix for URIs.

The only prefix currently used by App Orchestration is `api:`. This prefix points to the root of the API. On this server, the root of the API is located at:

       http://localhost/cam/api/

This means a curie such as `[api:Tenants]` actually refers to `http://localhost/cam/api/Tenants`.

### Self references

The objects returned by APIs have a property named `Href` which is a "self reference"; it informs the caller of the exact query that was performed when the object was returned.

For example, if you query tenants by name:

        GET [apiRoot]/Tenants?name=*acme*

Then the result will contain an `Href` property:

        [api:Tenants?name=*acme*]

### Related-object references

The objects returned by APIs may have other related objects; for example, a Session Machine has a related Session Machine Catalog. These relationships are represented as ReferenceModels. The relationships allow the caller to see the related object's name and ID, and also contain an `Href` property that tells the caller the URI to query the full details of that related object.

Due to delegated administrator restrictions, it may be that the currently logged-in user is allowed to know of the existence of a related object, but may not be allowed to see the details of that object. When that is the case, the `Href` property will not be set. The caller should assume that the absense of the `Href` property implies that they are not authorized to query details of the related object.

### Related actions

After querying data or performing operations in App Orchestration, there are often actions related to the query or operation just performed; steps which the caller is likely to want to perform next. For example, after querying the list of Tenants configured in the system, the caller may wish to import another Tenant. Or, after validating a Session Machine Catalog for creation, the caller may wish to then actually create the Session Machine Catalog.

In general, related actions can be determined by examining the App Orchestration console UI. All links and actions available in the UI while viewing a particular page are considered related actions within the UI.

The related actions which are available at any point in time can vary based on both the calling user's permissions, and the state of the system. For example, if an object is currently being deleted, the caller cannot delete it again. The presence or absence of related actions can allow the caller to determine what actions are valid at the present moment in time, for the current caller to perform on the objects that have been returned.

Related actions can be found in the `RelatedActions` property of returned objects. Each item in the `RelatedActions` list is of type RelationModel and has a `Name` property which can be used to determine whether specific actions are present or absent in the set of currently-available related actions.

For example:

Request:

        GET https://srv01.my.com/cam/api/Tenants HTTP/1.1
        [...]

Response:

        HTTP/1.1 200 OK
        [...]

        {
            "Href": "https://srv01.my.com/cam/api/Tenants",
            "RelatedActions": {[{
                "Name": "GetTenant",
                "References": [...]
            }, {
                "Name": "ImportTenant",
                "References": [...]
            }]}
        }

Looking for the existence of specific related actions is the preferred method for clients to determine whether they have access to perform operations at any given time.