Example Developer Pages

EmpowerID provides several example developer pages—the Authorization API page, the Twilio Voice API page, and the Send Email API page—in the Web application that you can use to make API calls against your organization's data. These calls are real, however, they make no changes to the data so you can feel free to use them as needed to familiarize yourself with the Web API.

Authorization API Page

Your organization's resources, like its user accounts, groups and mailboxes, etc., as well as the resources internal to EmpowerID, such as its workflows and the pages of the EmpowerID Web application, are protected application resources secured by various EmpowerID operations. These operations are protected code objects that when executed allow resources to be accessed in a way that is consistent with the operation and the type of resource being accessed. Some examples include adding users to groups, creating mailboxes, updating user attributes or even viewing the pages of the Web application. Before users can access a resource in a given way, they must have the operation or operations that allows them to do so. If a user is missing a required operation access to that resource is denied. For example, if you tried to view the Authorization API page as an anonymous user, you would be directed to the login page where you would need to submit your credentials. Once authenticated, EmpowerID would call HasAccess() against your person for that page. If HasAccess() returns false, the page displays an access denied message.

If, on the other hand, HasAccess() returns true, EmpowerID displays the page and allows you to use it in a manner consistent with the purpose of the page. For the Authorization API page, this purpose is to allow you as a developer to call each of the HasAccess() methods against EmpowerID and view the format of the request payload.

For security reasons, each of these calls are HTTP POST methods.

To access the Authorization API page, log in to the EmpowerID Web application an an authorized user. Once logged in, you can access the page through the UI by expanding Developer and clicking Authorization API in the Navigation Sidebar, or you can type the URL for the page (https://<YourEmpowerIDWebServer>/EmpowerID/#custom/authorizationexample) in your browser's address bar and press ENTER.

In either case, you should be directed to the Authorization API page, which looks like the below image.

The Authorization API page is divided into endpoint sections with fields that allow you to call a specific HasAccess() check for a given person against a selected resource and view the JSON payload for that request. To use the page, you select the specific HasAccess() endpoint you want to call and add the necessary information to the fields on that page. This is demonstrated below by calling HasAccessToResource(). You call this endpoint when checking whether a person has access to a single resource object.

To call HasAccessToResource()

  1. Type the name of the person whose access you want to check in the Target Person field and then click the tile for that person.
  2. Type the name of the resource for which you want to check whether the person has access in the Resource field and then click the tile for that resource. For example, if you want to check whether the person has access to another person, you type the name of that other person.
  3. Type the specific operation you want to check in the Operation field. For example, if you want to see if the target person has the access needed to edit the job title of the other person, you type Edit JobTitle in the Operation field.
  4. To make the call, click Send.
  5. After sending the call an alert appears stating the result of the call.

    No alert appears if the parameters are not entered correctly.
  6. If an alert appears, click OK to close it.
  7. You should see the request payload the page sent to the endpoint in the JSON field.

    The payload is comprised of the following name/value pairs.

    • "person" : "EmpowerID Login of the target person"
    • "resource" : "GUID of the resource"
    • "operation" : "Display Name of the operation"

Calling other HasAccess() endpoints

In addition to the example shown above, the Authorization API allows you to call the below endpoints.

Has Access To Dual Resources


Checks whether a person can perform operations against two resources, such as approving a request to add a person to a group.

Endpoint

api/services/v1/hasaccess/hasaccesstodualresource

Example Request

{ person: 'ArnieApprover', resource1:'a5a1ce79-69a3-41e0-a434-5670f654123a', operation: 'Approve Group Membership', resource2: '0c80065b-48a1-40d9-abd9-3f7907fe3d28' }

Name/Value Pairs

  • "person" : "EmpowerID Login of the target person"
  • "resource1" : "GUID of the first resource"
  • "operation" : "Display Name of the dual operation"
  • "resource2" : "GUID of the second resource"

Response

Boolean


Has Role For Resource


Checks whether a person has a specific Access Level for a given resources. If the method returns true, then the person can perform the operations associated with the Access Level against the resource.

Endpoint

api/services/v1/hasaccess/hasroleforresource

Example Request

{ person: 'ArnieApprover', role:'Access Manager', resource:'fb5d20a8-334f-4575-8b36-2058943dd195' }

Name/Value Pairs

  • "person" : "EmpowerID Login of the target person"
  • "role" : "Display Name of the Access Level"
  • "resource" : "GUID of the resource"

Response

Boolean


Has Access to Workflow


Checks whether a person can initiate a specified workflow.

Endpoint

api/services/v1/hasaccess/hasaccesstoworkflow

Example Request

{ person: 'ArnieApprover', workflow:'Laptop Asset Provision' }

Name/Value Pairs

  • "person" : "EmpowerID Login of the target person"
  • "resource" : "Display Name of the workflow"

Response

Boolean


Has Access to Workflows


Checks whether a person can initiate the specified workflows.

Endpoint

api/services/v1/hasaccess/hasaccesstoworkflows

Example Request

{ person: 'ArnieApprover', workflows:'Create Shared Folders, Delete Shared Folders' }

Name/Value Pairs

  • "person" : "EmpowerID Login of the target person"
  • "workflows" : "Display Name of each workflow. Comma separated."

Response

Boolean


Has Access to Page


Checks whether a person has access to a specified page.

Endpoint

api/services/v1/hasaccess/hasaccesstopage

Example Request

{ person: 'ArnieApprover', page:'e780eb21-7908-4741-9e9a-61747732147c' }

Name/Value Pairs

  • "person" : "EmpowerID Login of the target person"
  • "page" : "GUID of the page"

Response

Boolean


Has Access to Pages


Checks whether a person has access to the specified pages.

Endpoint

api/services/v1/hasaccess/hasaccesstopages

Example Request

{ person: 'ArnieApprover', pages:'63f64ec8-b3a2-4085-8337-77385284b8a6, 10ad7ef4-7207-46f0-ae70-103bf3cf0110' }

Name/Value Pairs

  • "person" : "EmpowerID Login of the target person"
  • "pages" : "Protected Application Resource GUID of the pages. Comma separated."

Response

Boolean


Get Visible Child Controls for Application


Returns all child controls of a parent application that the person can see.

Endpoint

api/services/v1/hasaccess/getallowedcontrols

Example Request

{ person: 'ArnieApprover', application:'e4e51851-5450-4b6e-ae31-bf1f9eeef5c6' }

Name/Value Pairs

  • "person" : "EmpowerID Login of the target person"
  • "application" : "GUID of the parent application"

Response

GUID of each visible child control


Has Management Roles


Checks whether a person has the specified roles.

Endpoint

api/services/v1/hasaccess/hasmanagementroles

Example Request

{ person: '24754', managementRoles:'fff8153f-982e-4504-b687-2bbd1f8b7c42,fb5d20a8-334f-4575-8b36-2058943dd195' }

Name/Value Pairs

  • "person" : "PersonID of the target person"
  • "managmentRoles" : "GUID of each Management Role. Comma separated."

Response

Boolean


Is in Management Role


Checks whether a person has a specified Management Role.

Endpoint

api/services/v1/hasaccess/isinmanagementrole

Example Request

{ person: '24754', managementRole:'fff8153f-982e-4504-b687-2bbd1f8b7c42' }

Name/Value Pairs

  • "person" : "PersonID of the target person"
  • "managementRole" : "GUID of the Management Role"

Response

Boolean


Is in Group


Checks whether a person belongs to a specified group.

Endpoint

api/services/v1/hasaccess/isingroup

Example Request

{ person: '24754', group:'6c19c0f1-0a0a-4f1a-a526-2b8408aaf5be' }

Name/Value Pairs

  • "person" : "PersonID of the target person"
  • "group" : "GUID of the Group"

Response

Boolean


Has Groups


Checks whether a person belongs to the specified groups.

Endpoint

api/services/v1/hasaccess/hasgroups

Example Request

{ person: '24754', groups:'6c19c0f1-0a0a-4f1a-a526-2b8408aaf5be, 1089e2ef-67dc-484d-9b4b-c702822ffc0a' }

Name/Value Pairs

  • "person" : "PersonID of the target person"
  • "groups" : "GUID of each group. Comma separated."

Response

Boolean


Has Business Roles


Checks whether a person has the specified Business Roles.

Endpoint

api/services/v1/hasaccess/hasbusinessroles

Example Request

{ person: '24754', businessRoles:'2994477, 2994478, 3146825' }

Name/Value Pairs

  • "person" : "PersonID of the target person"
  • "businessRoles" : "ResourceID of each Business Role. Comma separated."

Response

Boolean


Is In Business Role


Checks whether a person has the specified Business Role.

Endpoint

api/services/v1/hasaccess/isinbusinessrole

Example Request

{ person: '24754', businessRole:'2994477' }

Name/Value Pairs

  • "person" : "PersonID of the target person"
  • "businessRole" : "ResourceID of the Business Role"

Response

Boolean


Is In Business Role and Location


Checks whether a person belongs to the specified Business Role and Location (OrgRoleOrgZone).

Endpoint

api/services/v1/hasaccess/isinbusinessroleandlocation

Example Request

{ person: '24754', businessRoleAndLocation:'3348' }

Name/Value Pairs

  • "person" : "PersonID of the target person"
  • "businessRoleAndLocation" : "OrgRoleOrgZoneID of the Business Role and Location (OrgRoleOrgZone)"

Response

Boolean

Twilio Voice API Page

This page demonstrates using EmpowerID to make API calls against an third-party application (Twilio) that has been registered in EmpowerID. This page specifically allows you to view the EmpowerID endpoint and request payload EmpowerID sends to Twilio to place call or SMS on your behalf. To get the most out of the page, it is helpful to have a Twilio account that you can register in EmpowerID as an OAuth Service Provider. This allows EmpowerID to pass the Account SID, Auth Token and Twilio phone number to Twilio, where the API call occurs. If you have a Twilio account that you would like to register in EmpowerID, expand the drop-down and follow the steps outlined there. Once you have registered the account in EmpowerID, you can use it to call or send an SMS.

Beyond registering your Twilio account in EmpowerID, to successfully call or send an SMS you need to have the following operations:
  • CallPerson - Allows you to call the specified person. You need to have this operation allowed for each person you call.
  • CallNumber - Allows you to call phone numbers as the EmpowerID system. This operation is against the EmpowerID system.
  • SMSPerson - Allows you to SMS the specified person. You need to have this operation allowed for each person you SMS.
  • SMSNumber - Allows you to SMS phone numbers as the EmpowerID system. This is against the EmpowerID system.

  • Registering your Twilio account in EmpowerID
    1. From the EmpowerID Web application, navigate to OAuth Application Manager by expanding Admin > Applications > SSO Connections and clicking OAuth in the Navigation Sidebar.
    2. In OAuth Application Manager, search for Twilio and click the Provider link.
    3. This opens the OAuth Service Provider Details page for Twilio.

    4. From the grid, click the Edit button for the Twilio provider.
    5. In the Edit dialog that appears, do the following:
      1. Enter the Account SID for your Twilio account in the Consumer Key field.
      2. Enter the Auth Token for your Twilio account in the Consumer Secret field.
      3. Enter the Twilio phone number for your Twilio account in the Sender Identifier field.
      4. Click Save.

To access the Twilio Voice API page, log in to the EmpowerID Web application an an authorized user. Once logged in, you can access the page through the UI by expanding Developer and clicking Twilio Voice API in the Navigation Sidebar, or you can type the URL for the page (https://<YourEmpowerIDWebServer>/EmpowerID/#custom/twilioexample) in your browser's address bar and press ENTER.

In either case, you should be directed to the Twilio Voice API page, which looks like the below image.

The Twilio Voice API page is divided into two endpoint sections with fields that allow you to send an API request to Twilio to either call or SMS a specified number. This is demonstrated below.

If you are sending a request to call a person, that person must have a phone number that is registered in EmpowerID.

To Send a Call

  1. If you are calling a person, type the name of that person in the Person To Call field and then click the tile for that person.
  2. If you wish to send a custom voice message to the person, alter the text in the Message field. Please note that the format cannot be changed or the call will fail.
  3. If you are calling one or more numbers, type the numbers as comma-separated values in the Phone Numbers field. Phone numbers must begin with country code and cannot contain dashes or spaces.
  4. Select Twilio from the OAuth Consumer API Key drop-down.
  5. After sending the request an alert appears stating the result.

    No alert appears if the parameters are not entered correctly.
  6. If an alert appears, click OK to close it.
  7. You should see the request payload the page sent to the endpoint in the JSON field.

    The payload is comprised of the following name/value pairs.

    • "personIDs" : "PersonID of the person being called"
    • "message" : "Voice message sent by Twilio"
    • "oauthApplicationID" : "GUID of the OAuth Service Provider"

To Send an SMS

  1. If you sending an SMS to a person, type the name of that person in the Person To SMS field and then click the tile for that person.
  2. Type the content of the SMS in the Message field.
  3. If you are sending an SMS to one or more numbers, type the numbers as comma-separated values in the Phone Numbers field. Phone numbers must begin with country code and cannot contain dashes or spaces.
  4. Select Twilio from the OAuth Consumer API Key drop-down.
  5. ``

    After sending the request an alert appears stating the result.


    No alert appears if the parameters are not entered correctly.

  6. If an alert appears, click OK to close it.
  7. You should see the request payload the page sent to the endpoint in the JSON field.

    The payload is comprised of the following name/value pairs.

    • "personIDs" : "PersonID of the person being called"
    • "message" : "SMS message sent by Twilio"
    • "oauthApplicationID" : "GUID of the OAuth Service Provider"

Send Email API Page

This page demonstrates using the EmpowerID Web API to send emails. The page allows you to view the EmpowerID endpoint for the call and the request payload. To successfully send an email using the API, you need to have the following operations:

  • Send Email - Allows you to send an email to the specified person. You need to have this operation allowed for each person you send an email.
  • Send Email - Allows you to send emails to specified email addresses as the EmpowerID system. This operation is against the EmpowerID System

To access the Send Email API page, log in to the EmpowerID Web application an an authorized user. Once logged in, you can access the page through the UI by expanding Developer and clicking Send Email API in the Navigation Sidebar, or you can type the URL for the page (https://<YourEmpowerIDWebServer>//EmpowerID/#custom/sendemailexample) in your browser's address bar and press ENTER.

In either case, you should be directed to the Send Email API page, which looks like the below image.

If you are emailing a person, that person must have an email address that is registered in EmpowerID.

To Send Email

  1. If you are emailing a person, type the name of that person in the Target Person field and then click the tile for that person.
  2. Type the subject in the Subject field.
  3. Type the email message in the Message field.
  4. If you are sending the email to one or more email addresses, type those addresses in the Email Addresses field as comma-separated values.
  5. Click Send.
  6. After sending the request an alert appears stating the result.

    No alert appears if the parameters are not entered correctly.
  7. If an alert appears, click OK to close it.
  8. You should see the request payload the page sent to the endpoint in the JSON field.

    The payload is comprised of the following name/value pairs.

    • "personIDs" : "PersonID of the person being sent the email"
    • "body" : "Email message"
    • "emailAddresses" : "Email addresses of message recipients"
    • "subject" : "Email subject"