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#

Returns the user information for the specified user id.

Request#

MethodURL
GETapi/integration/v2/users/:id
FieldValueTypeDescription
idIntegerURLThe 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#

Not Found: HTTP 404

KeyValueDescription
response_codeStringnot_found
messageStringMore information about the response

Example:

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

Invalid Parameter

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

Create New User#

Request#

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

Response#

Successful Response#

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.

Successful Response Sample#

HTTP/1.1 201 Created

{   "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#

Updates an existing user by the given id.

Request#

MethodURL
PATCH or PUTapi/integration/v2/users/:id
KeyValueTypeDescription
idIntegerURLThe id of the user to update
email optionalStringBodyThe primary email address for the user
first_name optionalStringBodyThe user's given name
last_name optionalStringBodyThe user's surname
mobile_phone_number optionalString (E.164 International Standard Format)BodyThe user's mobile phone number for SMS MFA
locale optionalString (ISO 639-1 code)BodyLanguage code for the user
locked optionaltrue / false (default false)BodyWhether the user's account is locked which prevents logging in
Sample Request#
{   "mobile_phone_number": "+18885559999"}

Response#

On success, this returns the updated user information.

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}
Unsuccessful Response#

Not Found: HTTP 404

KeyValueDescription
response_codeStringnot_found
messageStringMore information about the response

Example:

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

Invalid Data

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

Invalid Parameter

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. Offboarding a user will also remove their link to the local workstation account, so that a different eGuardian user can pair with the same local user account.

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.

Offboarded users can optionally be soft deleted in the same request. This retains all user data, history, and audit logs while removing the account from the list of users. A new user account with the same email address may be onboarded, but will not retain the user's history. A soft deleted user account may only be restored by SecureAuth personnel.

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. An additional field, delete, indicates that the user account should be soft deleted while retaining their data, history, and audit logs.

KeyValueTypeDescription
email optionalStringBodyThe primary email address for the user
id optionalIntegerBodyThe user identifier
delete optionalBooleanBodyWhether to soft delete the user (default false)
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 and soft deleting one:

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

Response#

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

Successful Response#
{    "response_code": "success"}
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.

Failure Response

KeyValueDescription
response_codeStringfailure
messageStringInformative message describing the error

Role Management#

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

List All Roles#

Returns all available roles.

Request#

MethodURL
GETapi/integration/v2/roles

Response#

Successful Response#

An array of Role objects:

KeyValueDescription
nameStringThe unique identifier for the role
Successful Response Example#

HTTP/1.1 200 OK

[    {        "name": "org_admin"    },    {        "name": "help_desk"    }]

List Roles Assigned to a User#

Returns all the roles assigned to a specific user.

Request#

MethodURL
GETapi/integration/v2/users/:user_id/roles
KeyValueTypeDescription
user_idIntegerURLThe id of the user to list the assigned roles for

Response#

Successful Response#

An array of Role objects:

KeyValueDescription
nameStringThe unique identifier for the role
Successful Response Example#

HTTP/1.1 200 OK

[    {        "name": "org_admin"    },    {        "name": "help_desk"    }]
Unsuccessful Response#

Not Found: HTTP 404

KeyValueDescription
response_codeStringnot_found
messageStringMore information about the response

Example:

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

Invalid Parameter

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

List Users With an Assigned Role#

Returns all the users who have the specified role assigned to them.

Request#

MethodURL
GETapi/integration/v2/roles/:role_name/users
KeyValueTypeDescription
role_nameStringURLThe role identifier to list the users assigned to that role

Response#

And array of User objects:

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    },    {        "id": 2,        "email": "user1@acceptto.com",        "first_name": "user",        "last_name":  "one",        "mobile_phone_number": "+12345678",        "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#

Not Found: HTTP 404

KeyValueDescription
response_codeStringnot_found
messageStringMore information about the response

Example:

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

Invalid Parameter

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

Assign a Role to a User#

Assigns the given role to the specified user.

Request#

MethodURL
POSTapi/integration/v2/users/:user_id/roles
KeyValueTypeDescription
user_idIntegerURLThe user identifier
nameStringBodyThe role identifier
Sample Request#
{   "name": "help_desk"}

Response#

On success, returns a success response code in the body with 201 (Created) HTTP status.

Successful Response#

HTTP/1.1 201 Created

{    "response_code": "success"}
Unsuccessful Response#

Not Found: HTTP 404

KeyValueDescription
response_codeStringnot_found
messageStringMore information about the response

Example:

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

Invalid Parameter

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

Unassign a Role from a User#

Removes the given role from the specified user.

Request#

MethodURL
DELETEapi/integration/v2/users/:user_id/roles/:name
KeyValueTypeDescription
user_idIntegerURLThe user identifier
nameStringURLThe role identifier

Response#

On success, returns a success response code in the body with 200 (OK) HTTP status.

Successful Response#

HTTP/1.1 200 OK

{    "response_code": "success"}
Unsuccessful Response#

Not Found: HTTP 404

KeyValueDescription
response_codeStringnot_found
messageStringMore information about the response

Example:

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

Invalid Parameter

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