How To: Call The Identity Hub API

With The Identity Hub API you can obtain information about an identity. The Identity Hub API is a REST API, returns the results in JSON format and uses OAuth 2 for authorization.

Getting an Access Token

There are several ways to get an Access Token:

Using an OAuth flow

You can use one of the available OAuth flows to get an Access Token. For more information see the specific topic.

Flow See
Implicit Grant How To: Perform OAuth Implicit Grant
Code Grant How To: Perform OAuth Code Grant
Client Credentials Grant How To: Perform OAuth Client Credentials Grant

Using WS-Federation

When your application using WS-Federation to let your users perform a sign-in, the following claim is always present and contains a valid Access Token:

http://schemas.u2uconsult.com/ws/2014/03/identity/claims/accesstoken

Calling an API method

There are two ways to call an API methods:

Passing the Access Token in the Authorization Header (recommended)

GET /{tenant}/api/identity/v1 
Authorization: Bearer 57600
Host: www.theidentityhub.com

Passing the Access Token as a query string parameter

GET /{tenant}/api/identity/v1?access_token=57600

Code Examples

To install the NuGet Package search for TheIdentityHub.Windows81 in the NuGet Package Manager.


// Your ClientId
var clientId = "[YOUR_CLIENT_ID]";

// Your base URL
var baseUrl = new Uri("https://www.theidentityhub.com/{tenant}");

// Initialize
var identityService = new IdentityService(clientId, baseUrl);

// Authenticate
if(await identityService.TryAuthenticateAsync())
{
    // Get profile info.
    var profile = await identityService.GetProfileAsync();

    // Get friends info.
    var friends = await identityService.GetFriendsAsync();

    // Get roles info.
    var roles = await identityService.GetRolesAsync();
}

To install the NuGet Package search for TheIdentityHub.WindowsDesktop in the NuGet Package Manager.


// Your ClientId
var clientId = "[YOUR_CLIENT_ID]";

// Your base URL
var baseUrl = new Uri("https://www.theidentityhub.com/{tenant}");

// Initialize
var identityService = new IdentityService(clientId, baseUrl);

// Authenticate
if(await identityService.TryAuthenticateAsync())
{
    // Get profile info.
    var profile = await identityService.GetProfileAsync();

    // Get friends info.
    var friends = await identityService.GetFriendsAsync();

    // Get roles info.
    var roles = await identityService.GetRolesAsync();
}


using (var client = new HttpClient())
{
    var url = "https://www.theidentityhub.com/{tenant}/api/identity/v1";
    client.DefaultRequestHeaders.Add("Authorization", "Bearer " + accessToken);
    var response = await client.GetStringAsync(url);
    // Parse JSON response.
    ....
}
                    


using (var client = new HttpClient())
{
    var url = "https://www.theidentityhub.com/{tenant}/api/identity/v1";
    client.DefaultRequestHeaders.Authorization = new HttpCredentialsHeaderValue("Bearer", accessToken);
    var response = await client.GetStringAsync(new Uri(this.baseUrl, "api/identity/v1/")).AsTask().ConfigureAwait(continueOnCapturedContext: false);
    // Parse JSON response.
    ....
}
                    

To install the AngularJS SDK, run the following bower command in a command prompt


    bower install theidentityhub-angular

    angular.module('[YOUR_APP_NAME]', ['identityHub'])
        .config(function (identityServiceProvider) {
                identityServiceProvider.config({
                baseUrl: "https://www.theidentityhub.com/{tenant}",
                clientId: "[YOUR_CLIENT_ID]",
                redirectUri: "[YOUR_REDIRECT_URI]",
                popup: false
            });
        });

    identityService.signIn();

How To: Sign into your AngularJS App with The Identity Hub

To install the jQuery SDK, run the following bower command in a command prompt


    bower install theidentityhub-jquery

 $.identityService.config({
        baseUrl: "https://www.theidentityhub.com/{tenant}",
        clientId: "[YOUR_CLIENT_ID]",
        redirectUri: "[YOUR_REDIRECT_URI]",
        popup: false
    });

    identityService.signIn();

How To: Sign into your AngularJS App with The Identity Hub

To install the NuGet Package search for TheIdentityHub.AspNet in the NuGet Package Manager.

Getting Profile Information from Claims

If your ASP.NET site uses The Identity Hub as a WS-Federation Identity Provider you can use the following code to get the information passed as Claims.

using TheIdentityHub;
var displayName = this.User.DisplayName();
var smallPicture = this.User.SmallPicture();
var emailAddresses = this.User.EmailAddresses();
...
             

Initialize the Identity Service


// Your ClientId
var clientId = "";
// Your base URL
var baseUrl = new Uri("https://www.theidentityhub.com/{tenant}");
// Initialize
var identityService = new IdentityService(clientId, baseUrl);
                     
If you use the constructor as done above, the SDK will try to get the Access Token from the access token claim on the current principal. If no such claim is found, an error will be thrown.

If you want to specify your own token, use the constructor as shown below.

Set AccessToken


// Access Token
var accessToken = "546465qzer-Lm";
// Initialize
var identityService = new IdentityService(clientId, baseUrl, accessToken);
                     

Getting Profile Information


// Get profile info.
var profile = await identityService.GetProfileAsync();
                     

Update Profile Information


// Update profile info.
await identityService.UpdateProfileAsync(profile);
                     

ASP.NET Server Side SDK

Handling the response

When a call is successful, the method returns the result in JSON format. An example is shown below.

{
  "displayName": "John Doe",
  "emailAddress": "JohnDoe@mail.com",
  "emailAddresses": [
    "JohnDoe@mail.com",
    "JohnDoe@mailinator.com"
  ],
  "emailAddressVerified": true,
  "givenName": "John",
  "givenNames": [
    "John",
    "John Davis"
  ],
  "identityId": "45789465489797843004",
  "isEditable": true,
  "largePictures": [
    "https://fake.url/pic1.jpg",
    "https://fake2.url/pic17.png"
  ],
  "localities": [
    "en-US",
    "nl-BE"
  ],
  "locality": "en-US",
  "mediumPictures": [
    "https://fake.url/pic7m.jpg",
    "https://fake2.url/pic29m.png"
  ],
  "privatePersonalIdentifier": "8945645642133340",
  "smallPictures": [
    "https://fake.url/pic7aas.jpg",
    "https://fake2.url/picaa9s.png"
  ],
  "surname": "Doe",
  "surnames": [
    "Doe"
  ],
  "userName": "07894564561379874"
}

Available API methods

Method See Available with
GET {tenant}/api/identity/v1 GET {tenant}/api/identity/v1 User Token
GET {tenant}/api/identity/v1/{id} GET {tenant}/api/identity/v1/{id} User Token/App Token
GET {tenant}/api/identity/v1/accounts GET {tenant}/api/identity/v1/accounts User Token
GET {tenant}/api/identity/v1/{id}/accounts GET {tenant}/api/identity/v1/{id}/accounts User Token/App Token (Coming soon)
GET {tenant}/api/identity/v1/friends GET {tenant}/api/identity/v1/friends User Token
GET {tenant}/api/identity/v1/{id}/friends GET {tenant}/api/identity/v1/{id}/friends User Token/App Token (Coming soon)
PUT {tenant}/api/identity/v1 PUT {tenant}/api/identity/v1 User Token
DELETE {tenant}/api/identity/v1 DELETE {tenant}/api/identity/v1 User Token
DELETE {tenant}/api/identity/v1/{id} DELETE {tenant}/api/identity/v1/{id} User Token/App Token

Related sections

GET {tenant}/oauth2/v1/auth
POST {tenant}/oauth2/v1/token
GET {tenant}/oauth2/v1/verify