Skip to main content

Object Management API

Overview#

This API is a RESTful API using OAuth for authentication and OAuth scopes for authorization. In order to call this API, you will need to have an application in eGuardian that is granted the necessary OAuth scopes. You will need the UID of that application and its Secret.

Authenticating#

This REST API uses the OAuth client_credentials authentication flow.

Get Access Token from the OAuth authorization endpoint (/oauth/token)

ParameterTypeDescription
grant_typeStringclient_credentials. Indicates the desired OAuth flow
client_idStringThe UID of the calling application in eGuardian
client_secretStringThe client secret for the application in eGuardian
scopeStringA space-delimited list of scopes to be issued to the access token

Sample Request#

{   "grant_type": "client_credentials",   "client_id": "YOUR_EGUARDIAN_APPLICATION_UID",   "client_secret": "YOUR_EGUARDIAN_APPLICATION_SECRET",   "scope": "REQUESTED_SCOPES"}

This will return the access token if that application is authorized with the requested scopes.

info

The generated access tokens are more than 255 bytes in length, so when storing them make sure to have at least 500 bytes of storage available or else they will be truncated.

Sample Response#

{   "access_token": "YOUR_OAUTH_ACCESS_TOKEN",   "token_type": "Bearer",   "expires_in": 7200,   "scope": "public",   "created_at": 1630710187}

Call API endpoint, sending the access token in the Authorization HTTP header with Bearer:

Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN

Response Overview#

HTTP Status Codes#

The HTTP status of the response will indicate the general disposition of the request:

CodeMeaning
2xxEverything went well, the requested data will be in the content field
422We were unable to process the given data, check the errors field for details
4xxSome other error occurred, check the message field for more detail

Response Body#

The body of the response is a JWT—signed by our private key—containing the following keys:

FieldValueDescription
response_codeStringA code indicating the general nature of the response (e.g. success)
contentJSONThe output data from a successful request. Will only be present if response_code is success
errorsJSONA mapping of fields to their error messages (e.g. { "email": ["can't be blank"] }). Only present when response_code is invalid
messageStringAn informative message describing the error. Present when response code is neither success nor invalid

User Management#

User management requires the admin_own_users OAuth scope on the access token.

Get User Info#

This is a RESTful API endpoint and takes the user id to look up as the last component of the URL.

Request#

MethodURL
GETapi/integration/v2/users/:id
FieldValueDescription
idIntegerThe id of the user to fetch

Response#

Successful Response#
KeyValueDescription
idIntegerThe unique identifier for the user
emailStringThe user's primary email address
first_nameStringThe user's given name
last_nameStringThe user's surname
mobile_phone_numberStringThe mobile phone number for use by SMS, in E.164 International Standard Format
created_atDateTimeWhen the user was first created, in ISO-8601 format
updated_atDateTimeWhen the user was last updated, in ISO-8601 format
last_login_atDateTimeThe time of the user's last successful login, in ISO-8601 format
lockedBooleanWhether the user's account is locked which prevents logging in

Successful Response Example#

HTTP/1.1 200 OK

{   "id": 1,   "email": "abe.lincoln@acceptto.com",   "first_name": "Abe",   "last_name":  "Lincoln",   "mobile_phone_number": "+18005551212",   "created_at": "2021-08-24T14:33:32.804-07:00",   "updated_at": "2021-11-19T08:07:22.976-07:00",   "last_login_at": "2021-11-19T08:07:21.223-07:00",   "locked": false}

Unsuccessful Response#

{   "response_code": "not_found",   "message": "Could not find the specified user"}

Not Found: HTTP 404

KeyValueDescription
response_codeStringnot_found
messageString"Could not find the specified user"

Unsuccessful Response

KeyValueDescription
response_codeStringCode indicating type of error. e.g. invalid_parameter
messageStringInformative message describing the error

Create New User#

Create User Request#

MethodURL
POSTapi/integration/v2/users
KeyValueDescription
emailStringThe primary email address for the user
first_name optionalStringThe user's given name
last_name optionalStringThe user's surname
mobile_phone_number optionalString (E.164 International Standard Format)The user's mobile phone number for SMS MFA
locale optionalString (ISO 639-1 code)Language code for the user
locked optionaltrue / false (default false)Whether the user's account is locked which prevents logging in
Create User Sample Request#
{   "email": "abe.lincoln@acceptto.com",   "first_name": "Abe",   "last_name": "Lincoln",   "mobile_phone_number": "+18005551212"}
Create User Successful Request#

On success HTTP status 201 (Created) is returned and the user details of the newly created user are returned in the body. This includes the id of the new user.

HTTP/1.1 201 Created

Create User Sample Response#
{   "id": 1,   "email": "abe.lincoln@acceptto.com",   "first_name": "Abe",   "last_name":  "Lincoln",   "mobile_phone_number": "+18005551212",   "created_at": "2021-08-24T14:33:32.804-07:00",   "updated_at": "2021-08-24T14:33:32.804-07:00",   "last_login_at": null,   "locked": false}

Update Existing User#

This is a RESTful API endpoint and takes the user id to update as the last component of the URL.

Update User Request#

MethodURL
PATCH or PUTapi/integration/v2/users/:id
KeyValueDescription
email optionalStringThe primary email address for the user
first_name optionalStringThe user's given name
last_name optionalStringThe user's surname
mobile_phone_number optionalString (E.164 International Standard Format)The user's mobile phone number for SMS MFA
locale optionalString (ISO 639-1 code)Language code for the user
locked optionaltrue / false (default false)Whether the user's account is locked which prevents logging in

Update User Sample Request#

{   "mobile_phone_number": "+18885559999"}

Update User Response#

On success, this returns the updated user information.

Update User Successful Response#
{   "id": 1,   "email": "abe.lincoln@acceptto.com",   "first_name": "Abe",   "last_name":  "Lincoln",   "mobile_phone_number": "+18885559999",   "created_at": "2021-08-24T14:33:32.804-07:00",   "updated_at": "2022-01-14T12:47:22.976-07:00",   "last_login_at": "2021-11-19T08:07:21.223-07:00",   "locked": false}

Update User Unsuccessful Response#

Not Found: HTTP 404

KeyValueDescription
response_codeStringnot_found
messageString"Could not find the specified user"

Invalid Data

KeyValueDescription
response_codeStringinvalid
errorsJSONMap giving the values that had errors and what those errors were.

Unsuccessful Response

KeyValueDescription
response_codeStringCode indicating type of error. e.g. invalid_parameter
messageStringInformative message describing the error

Offboard User#

This endpoint allows for offboarding of one or more users. For each user to be offboarded, the following steps will be performed:

  1. Account lock. The user's eGuardian account will be locked, causing all authentications to be rejected. Even if the user's mobile device is re-paired, any attempt to re-pair a workstation will fail while the user's account is locked.

  2. Mobile device unpairing. All of the user's paired mobile devices will be immediately unpaired in eGuardian, and will no longer be available to the user for push-based authentications. If the mobile device is online at the time of offboarding, the It'sMe app to return to the initial pairing screen. If the mobile device is not online, this will happen when network connectivity resumes. The user will no longer have access to their TOTP offline codes, or use of their mobile device for push authentications. (Note: When a user is offboarded, the organization is expected to disable their email account to prevent the possibility of re-pairing.)

  3. Workstation unpairing. All of the user's paired workstations will be immediately unpaired in eGuardian. If the workstation is online at the time of offboarding, it will immediately lock the desktop. The user will be unable to log in again without re-pairing the workstation, which will be impossible because the user's eGuardian account will be locked and the user's mobile devices will be unpaired. If the workstation is not online, this locking and unpairing will happen when network connectivity resumes.

If a user has been offboarded in this manner, they can be onboarded again with the following steps:

  1. Restore the user's access to email, if it was disabled.
  2. Use the eGuardian dashboard to unlock the user's account. (Organization admin privileges are necessary for this step.)
  3. Ask the user to re-pair their mobile device.
  4. Ask the user to re-pair their workstation and log in.

The offboard endpoint allows offboarding multiple users at once. However, note that each call to the endpoint is atomic -- if any failure occurs for any user, no offboarding steps will be performed for any user.

Offboard User Request#

MethodURL
POSTapi/integration/v2/users/offboard

The request body should contain a JSON object with a single users key whose value is an array of objects used to identify a user. (The examples below should provide clarity.) Each user identification object should contain exactly one key used to identify the user -- either email or id -- but not both.

KeyValueDescription
email optionalStringThe primary email address for the user
id optionalIntegerThe unique identifier for the user

Offboard User Sample Requests#

Offboarding a single user identified by email address:

{    "users": [        {            "email": "abe.lincoln@acceptto.com"        }    ]}

Offboarding a single user identified by their unique eGuardian numeric identifier:

{    "users": [        {            "id": 511940        }    ]}

Offboarding multiple users:

{    "users": [        {            "email": "abe.lincoln@acceptto.com"        },        {            "email": "mark.twain@acceptto.com"        }    ]}

Offboard User Response#

On success, this endpoint returns a JSON object with the response_code set to success.

Offboard User Successful Response#
{    "response_code": "success"}

Offboard User Unsuccessful Response#

Not Found: HTTP 404

KeyValueDescription
response_codeStringnot_found
messageString"Could not find a user with email abe.lincoln@acceptto.com"

Invalid Parameter

KeyValueDescription
response_codeStringinvalid_parameter
messageStringAn explanation of the problematic parameter.

Unsuccessful Response

KeyValueDescription
response_codeStringfailure
messageStringInformative message describing the error