Using the Profiles on Demand API allows third-party applications to query profile information from Umbrella Faces after being authorized with OAuth2 authentication.

The interface is part of our standard web service offering and can be found in our swagger.yml documentation.

Preamble / General Notes

The Profiles on Demand API relies fully on the OAuth2 protocol to perform authentication and authorization to profiles. It is strongly suggested to get a general grasp of the OAuth 2.0 flows, specifically the Authorization Code and Client Credentials flows, before running any API related inquiries.

While the Profiles on Demand API does not currently support all data fields and entity types available in Umbrella Faces, the API is continuously being developed and extended. As a result, new data structures may be added to existing responses at any time without prior notice. It is therefore required to design a client application to only request information needed by the application as well as configure the application to not fail should there be additional (newly added) properties in the response.

Authentication

Application registration and certification

Third parties wishing to access data from Faces must provide the following details, which will be evaluated before any Oauth API can be accessed:

Umbrella will provide the application with a clientId and clientSecret to be used for development on our integration environment at https://hurricane.umbrellanet.ch/uf-test

Certification will be achieved by demonstrating the product accessing Faces using Oauth

Available OAuth Data-Scopes

Your application will be granted some or all of the following OAuth scopes for data access:

Please let our friendly support-staff know which scopes you’ll be requiring in order to provide which desired functionality. 

Supported OAuth2 Flows

Faces supports multiple Oauth2 grant flows, depending on the individual requirements of the client application. The following table lists possible flows:

Please let us know which OAuth flow you plan on supporting for your use case when requesting API credentials. If not otherwise specified, we’ll be supplying you with access to the Authorization Code flow.

Oauth2 Authorization Code Flow by example

Step 1: Request authorization code grant

The user is given a link to start the authorization process, including mandatory parameters

https://hurricane.umbrellanet.ch/uf-test/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL

Step 2: User authorizes the application

Upon clicking the link, the user must first login to Faces (unless they are already logged in). Then they will be prompted by the service to authorize or deny the application access.

An example authorization prompt may look like this:

Step 3: Application receives authorization code

If the user clicks "Authorize", Faces redirects to the application redirect URI which was specified in the request, along with an authorization code.

The redirect would look something like this:
https://your.application.com/callback?code=THE_AUTH_CODE

Step 4: Application requests refresh and access token

The application requests an access token from the API, by passing the authorization code along with authentication details using HTTP POST:

# https://CLIENT_ID:CLIENT_SECRET@hurricane.umbrellanet.ch/uf-test/oauth/token?grant_type=authorization_code&code=THE_AUTH_CODE&redirect_uri=CALLBACK_URL
curl -v -X POST \
    -H "Content-type: application/x-www-form-urlencoded" \
    -u client-id:client-secret \
    -d "grant_type=authorization_code" \
    -d "code=THE_AUTH_CODE" \
    -d "redirect_uri=CALLBACK_URL" \
    https://hurricane.umbrellanet.ch/uf-test/oauth/token

As a result, the application is granted short-lived access token used during API calls, as well as a long-lived refresh token which can be used for obtaining further access tokens:

{
    "access_token": "eb0afd63-7ad3-4b0f-a3cb-bacbbf4cac7c",
    "token_type": "bearer",
    "refresh_token": "0561038e-02d3-48e4-a859-399acacad59c",
    "expires_in": 3599
} 

Step 5: Get new access token

After the access token expires, a new one may be obtained similar to step 4:

# https://CLIENT_ID:CLIENT_SECRET@hurricane.umbrellanet.ch/uf-test/oauth/token?grant_type=refresh_token&refresh_token=REFRESH_TOKEN
curl -v -X POST \
    -H "Content-type: application/x-www-form-urlencoded" \
    -u client-id:client-secret \
    -d "grant_type=refresh_token" \
    -d "refresh_token=REFRESH_TOKEN" \
    https://hurricane.umbrellanet.ch/uf-test/oauth/token

As a result, a new access token will be issued. Our application may also issue a new refresh token in case the currently used one is due for expiration, which shall be stored upon reception and used from this point in time onwards.

Oauth2 Client Credentials Flow by example

When using the Client Credentials Flow, no user interaction is required, instead the authorization level of your application is directly configured within Umbrella Faces. As a result the Client Credentials Flow comprises of only a single step:

Step 1 out of 1: Get new access token

Whenever a new access token is needed (either because none is available or the old one has expired), a new one may be obtained by issuing a HTTP POST request to our token endpoint, supplying client_id and client_secret as HTTP Basic authentication, along with a grant_type of client_credentials:

# https://CLIENT_ID:CLIENT_SECRET@hurricane.umbrellanet.ch/uf-test/oauth/token?grant_type=client_credentials
curl -v -X POST \
    -H "Content-type: application/x-www-form-urlencoded" \
    -u client-id:client-secret \
    -d "grant_type=client_credentials" \
    https://hurricane.umbrellanet.ch/uf-test/oauth/token

As a result, a new access token will be issued.

ID token

In addition(or instead) of our OAuth API scopes, we do also support scopes resulting in generation of an ID-Token, which will be returned in Step 4 as well as Step 5 of the Authorization flow.
If only an ID-Token is desired, the OAuth process may be called with response_type=token which will trigger the OAuth 2.0 Implicit flow and only generate a short-lived access token without providing a refresh token.

The ID-Token will be presented in form of a JSON Web Token and will  be cryptographically signed using our Service Provider Certificate available at <faces_url>/saml/metadata,
i.e. https://hurricane.umbrellanet.ch/uf-test/saml/metadata

{
  "access_token": "f88a7119-b585-4c9c-9867-88a40aae41f8",
  "token_type": "bearer",
  "refresh_token": "bab32afe-acf8-4a8e-ba7c-ed567daa0ee4",
  "expires_in": 3599,
  "scope": "email openid profile",
  "id_token": "eyJhbGciOiJSUzI1NiJ9.eyJvcGVuaWQiOiIzZDkyMDVjYS1mMjY0LTRhZDgtYjFhYy1lNjQ1NTU3ZWFhOTkiLCJwcm9maWxlIjp7ImZpcnN0bmFtZSI6IlJlbW8iLCJwaG9uZSI6Iis0MTQ0MTIzNDU2NyIsImRpc3BsYXluYW1lIjoiSGVyciBSZW1vIFLDpGJlciIsIm5hbWUiOiJSw6RiZXIifSwiZW1haWwiOiJyZW1vLnRlc3RAdW1icmVsbGEuY2gifQ.ni2_4eszvqV5JgWBzJNmQ8jq225_7i-TiMAFzSGDSkPt6J5CTPSQF5wsq_Og5tOzd39nybGfwRzDyAkAOWinU2_djUv58gMx095U77ccSlSVYca6sn8t8WL62v8AOPSO9h8ok52nQpjtZFWcni4KABlcCKd_feT_5KjAmsRQwf7NZ0gqkoP3Y4Ymo454N8ezu822slF-ub4UdA1VBHDZuCJtQWbdsT2Cfep1NWRf3by_uP2s6yxHcHmQ0R_kYwXKMW2SbxyGo821cN-sxXYmppb4ipDtPKC7ANUYc5wZQ2Gp0gAenMIfxooz0njkEWKKMq3pwZWNJnWHDwVsluqI_w"
} 

Decoded ID-Token

The following extract depicts a decoded ID-Token from the value of "id_token" in the response above

{
  "openid": "3d9205ca-f264-4ad8-b1ac-e645557eaa99",
  "profile": {
    "firstname": "Remo",
    "phone": "+41441234567",
    "displayname": "Herr Remo Räber",
    "name": "Räber"
  },
  "email": "remo.test@umbrella.ch"
} 

Profiles API

 Search company profile

Allows searching through a paged list of company profiles. This API can be used to narrow-down the traveler profile search by company.

Parameters

curl -v -H "Authorization: Bearer <token>" https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/companies?q=acme&page=0&pageSize=10

{
	"moreResults": false,
	"results": [{
		"uuid": "b9321d7e-9d72-4e80-ac49-d3aa38169175",
		"name": "ACME Inc."
	}]
}

Get company profile

Retrieves the details of a single company profile.

Parameters

curl -v -H "Authorization: Bearer <token>" \
    https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/company/b9321d7e-9d72-4e80-ac49-d3aa38169175?sections=CONTACT_DATA,MEMBERSHIPS

{
	"uuid": "dba95fe6-873c-4499-be0c-d3aa38169175",
	"externalNr": "00001",
	"name": "Demo GmbH",
	"shortname": "DEMO-1",
	"data": {
		"contact": {
			"street": "Binzstrasse 33",
			"street2": null,
			"zipCode": "8620",
			"place": "Wetzikon",
			"countryCode": "CH"
		},
		"memberships": {
			"airline": [{
				"uuid": "6bd21d65-0671-4196-8fd1-4de9f4ce9071",
				"alliance": "LH",
				"memberNumber": "DEMODEMO123",
				"type": "SPECIAL_KEYWORD"
			}],
			"hotel": [],
			"rentalCar": []
		},
		"genericValues": {}
	}
} 

Company profile sections overview

The following sections are currently available in accordance with our Swagger schema definition:

Create new company profile

Create a new company profile

curl -v -X POST \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    --data '{
    "externalNr": "1337",
    "name": "Umbrella Organisation U+O AG",
    "shortname": "UMBRELLA",
    "data": {
        "contact": {
            "street": "Binzstrasse 33",
            "zipCode": "8620",
            "place": "Wetzikon",
            "countryCode": "CH"
        },
        "genericValues": {
            "costCenter": "1230A"
        },
        "agency": {
            "uuid": "52b166c5-4990-49bb-b1f1-d3aa38169175"
        }
    }
}' https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/company

Example response

The profile, including any sections populated by the request, will be reported back, including the newly generated UUID - see Get company profile

Implementation notes

The data structure is the same as is output in Get company profile  with the following exceptions:

• Company profile UUID cannot be provided in the JSON

For creating of a new profile, the following required properties must always be populated:

• name

• shortname

Faces will apply default validation logic as seen on our Web UI and CSV interfaces and will report validation errors to the caller without saving the profile.

Update existing company profile

curl -v -X PATCH \
    -H "Authorization: Bearer <token>" \
    --data '{
  "externalNr": "0815",
  "name": "ACME Incorporated",
  "shortname": "ACME-INC”,
  "data": {
    "memberships": {
      "airline": [
				{
					"alliance": "LH",
					"memberNumber": "DEMODEMO123",
					"type": "SPECIAL_KEYWORD"
				}				
			]
    }
  }
}' https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/company/b9321d7e-9d72-4e80-ac49-d3a

curl -v -X DELETE \
    -H "Authorization: Bearer <token>" \
    https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/company/b9321d7e-9d72-4e80-ac49-d3aa38169175