ExUsing Using the Profiles on Demand API allows third-party applications to query profile information from Umbrella Faces after being authorized with OAuth2 authentication.
...
Third parties wishing to access data from Faces must provide the following details, which will be evaluated before any Oauth API can be accessed:
Field | Description |
---|---|
Application Name | Application name, which will be shown to the user |
Application Purpose | Short description of what the application wants to achieve using the Oauth2 enabled APIs |
Desired OAuth Scopes | OAuth Scopes requested by the application see ----todo OauthScopes --- Available OAuth Data-Scopes |
Desired OAuth Flow(s) | One or more OAuth flows, see ....todo OAuthFlows... Supported OAuth2 Flows By default you will be granted access to the Authorization Code flow, which requires user interaction to authorize your application, however depending on your applications purpose it may be possible to setup a different flow (For example to allow unlimited access to all profiles belonging to your own travel agency in case you’re implementing an in-house application) |
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
AnchorOAuthScopes OAuthScopes
Available OAuth Data-Scopes
OAuthScopes | |
OAuthScopes |
Your application will be granted some or all of the following OAuth scopes for data access:
Scope | Description |
---|---|
api.profilesondemand.read |
Access to the Profiles API (read only) |
api.profilesondemand.write |
Access to the Profiles API (write) |
openid |
Required scope when requesting an ID-Token for “Login using Faces” functionality |
agencyid |
...
Optional scope to be included in and ID-Token. Please see the section Usage of an ID token within this document. | |
Optional scope to be included in and ID-Token. Please see the section Usage of an ID token within this document. | |
profile | Optional scope to be included in and ID-Token. Please see the section Usage of an ID token within this document. |
Please let our friendly support-staff know which scopes you’ll be requiring in order to provide which desired functionality.
...
Faces supports multiple Oauth2 grant flows, depending on the individual requirements of the client application. The following table lists possible flows:
Type | Description | Restrictions |
---|---|---|
Authorization Code | Allows an application to act on behalf of a (or multiple) specific user within Faces. The Authorization Code Flow requires the client application to open a popup-window where an user signs into Faces and explicitly allows access. Once Access has been granted, a refresh-token is issued which allows further access without additional human interaction. | Not all API operations may be available, depending on the authorization level of the user. (e.g. company data can not be queried or updated by a traveller) |
Implicit | Similar to the Authorization Code flow, with the difference that no refresh-token will be issued and thus only temporary access of maximum one hour is possible before re-confirmation is needed. | Same as for Authorization Code. |
Client Credentials | Currently allows a specific OAuth2 Client to be linked to a specific travel agency in Faces. No end-user interaction is required | ID-Tokens cannot be requested since the access is not tied to a specific user. |
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
TODO
ID token
TODO
Step 1: Request authorization code grant
The user is given a link to start the authorization process, including mandatory parameters
Parameter | Description |
---|---|
response_type=code | Specifies the application is requesting an authorization code grant (value = always “code”) |
client_id=CLIENT_ID | The clientId which has been setup for the application |
redirect_uri=CALLBACK_URL | Where Faces redirects the user after an authorization code is granted (full URI, including http:// https:// or other prefix) |
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:
Parameter | Description |
---|---|
CLIENT_ID:CLIENT_SECRET | The clientId and clientSecret which has been setup for the application, sent as HTTP Basic authentication |
code=THE_AUTH_CODE | The authorization code received in step 3 |
redirect_uri=CALLBACK_URL | The same callback url as used in step 2 |
grant_type=authorization_code | Specifies that you are wanting to trade an authorization_code for a long-lived request token. |
Code Block | ||||
---|---|---|---|---|
| ||||
# 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:
Code Block | ||
---|---|---|
| ||
{
"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:
Code Block | ||||
---|---|---|---|---|
| ||||
# 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:
Code Block | ||||
---|---|---|---|---|
| ||||
# 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.
Anchor IDToken IDToken
ID token
IDToken | |
IDToken |
TODO
Anchor ProfilesAPI ProfilesAPI
Profiles API
ProfilesAPI | |
ProfilesAPI |
Search company profile
Scope | api.profilesondemand.read |
---|---|
Endpoint | api/v1/profiles/companies |
TODO |
Allows searching through a paged list of company profiles. This API can be used to narrow-down the traveler profile search by company.
Parameters
Name | Description | Validation |
---|---|---|
q | Freetext query for finding matching profiles | Required parameter |
page | Current page within the result set, starts at 0 | Optional, number >= 0 |
pageSize | Maximum number of results per page. Default 10 | Optional, number > 0 and <= 100 |
includeDetails | Specify whether the search response should include detailed profile data | Boolean value: true or false Optional, default: false |
detailSections | Specify additional profile areas to be returned if includeDetails is set to true. Only explicitly specified sections will be included. | Only the following sections are currently supported:
|
Example Request
https://hurricane.umbrellanet.ch/uf-test/api/v1/profiles/companies?q=acme&page=0&pageSize=10
...