Object Management API

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 to the API

This REST API uses the OAuth client_credentials authentication flow.

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

Parameter	Type	Description
grant_type	String	`client_credentials`. Indicates the desired OAuth flow
client_id	String	The `UID` of the calling application in eGuardian
client_secret	String	The client secret for the application in eGuardian
scope	String	A 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.

Note

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:

Code	Meaning
2xx	Everything went well, the requested data will be in the `content` field
422	We were unable to process the given data, check the `errors` field for details
4xx	Some 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:

Field	Type	Description
response_code	String	A code indicating the general nature of the response (e.g. `success`)
content	JSON	The output data from a successful request. Will only be present if response_code is `success`
errors	JSON	A mapping of fields to their error messages (e.g. `{ "email": ["can't be blank"] }`). Only present when response_code is `invalid`
message	String	An 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

Method	URL
GET	/api/integration/v2/users/{id}

Field	Value	Type	Description
id	Integer	URL	The id of the user to fetch

Response

Successful response

Key	Value	Description
id	Integer	The unique identifier for the user
email	String	The user's primary email address
first_name	String	The user's given name
last_name	String	The user's surname
mobile_phone_number	String	The mobile phone number for use by SMS, in E.164 International Standard Format
created_at	DateTime	When the user was first created, in ISO-8601 format
updated_at	DateTime	When the user was last updated, in ISO-8601 format
last_login_at	DateTime	The time of the user's last successful login, in ISO-8601 format
locked	Boolean	Whether 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

Key	Value	Description
response_code	String	`not_found`
message	String	More information about the response

Not Found: HTTP 404 Example

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

Invalid Parameter

Key	Value	Description
response_code	String	Code indicating type of error. e.g. `invalid_parameter`
message	String	Informative message describing the error

Create New User

Request

Method	URL
POST	/api/integration/v2/users

Key	Value	Type	Description
email	String	Body	The primary email address for the user
first_name `optional`	String	Body	The user's given name
last_name `optional`	String	Body	The user's surname
mobile_phone_number `optional`	String (E.164 International Standard Format)	body	The user's mobile phone number for SMS MFA
locale `optional`	String (ISO 639-1 code)	Body	Language code for the user
locked `optional`	`true` / `false` (default `false`)	Body	Whether 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

Method	URL
PATCH or PUT	/api/integration/v2/users/{id}

Key	Value	Type	Description
id	Integer	URL	The id of the user to update
email `optional`	String	URL	The primary email address for the user
first_name `optional`	String	Body	The user's given name
last_name `optional`	String	Body	The user's surname
mobile_phone_number `optional`	String (E.164 International Standard Format)	Body	The user's mobile phone number for SMS MFA
locale `optional`	String (ISO 639-1 code)	Body	Language code for the user
locked `optional`	`true` / `false` (default `false`)	Body	Whether 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

Key	Value	Description
response_code	String	`not_found`
message	String	More information about the response

Not Found: HTTP 404 Example

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

Invalid Data

Key	Value	Description
response_code	String	`invalid`
errors	JSON	Map giving the values that had errors and what those errors were.

Invalid Parameter

Key	Value	Description
response_code	String	Code indicating type of error. e.g. `invalid_parameter`
message	String	Informative 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:

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.
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.)
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:

Restore the user's access to email, if it was disabled.
Use the eGuardian dashboard to unlock the user's account. (Organization admin privileges are necessary for this step.)
Ask the user to re-pair their mobile device.
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

Method	URL
POST	/api/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.

Key	Value	Type	Description
email `optional`	String	Body	The primary email address for the user
id `optional`	Integer	Body	The unique identifier for the user
delete `optional`	Boolean	Body	Whether 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

Key	Value	Description
response_code	String	`not_found`
message	String	`"Could not find a user with email abe.lincoln@acceptto.com"`

Invalid Parameter

Key	Value	Description
response_code	String	`invalid_parameter`
message	String	An explanation of the problematic parameter.

Failure Response

Key	Value	Description
response_code	String	`failure`
message	String	Informative 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

Method	URL
GET	/api/integration/v2/roles

Response

Successful response

An array of Role objects:

Key	Value	Description
name	String	The 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

Method	URL
GET	/api/integration/v2/users/{user_id}/roles

Key	Value	Type	Description
user_id	Integer	URL	The id of the user to list the assigned roles for

Response

Successful response

An array of Role objects:

Key	Value	Description
name	String	The 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

Key	Value	Description
response_code	String	`not_found`
message	String	More information about the response

Not Found: HTTP 404 example

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

Invalid Parameter

Key	Value	Description
response_code	String	Code indicating type of error. e.g. `invalid_parameter`
message	String	Informative message describing the error

List Users With an Assigned Role

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

Request

Method	URL
GET	/api/integration/v2/roles/{role_name}/users

Key	Value	Type	Description
role_name	String	URL	The role identifier to list the users assigned to that role

Response

And array of User objects:

Key	Value	Description
id	Integer	The unique identifier for the user
email	String	The user's primary email address
first_name	String	The user's given name
last_name	String	The user's surname
mobile_phone_number	String	The mobile phone number for use by SMS, in E.164 International Standard Format
created_at	DateTime	When the user was first created, in ISO-8601 format
updated_at	DateTime	When the user was last updated, in ISO-8601 format
last_login_at	DateTime	The time of the user's last successful login, in ISO-8601 format
locked	Boolean	Whether 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

Key	Value	Description
response_code	String	`not_found`
message	String	More information about the response

Not Found: HTTP 404 example

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

Invalid Parameter

Key	Value	Description
response_code	String	Code indicating type of error. e.g. `invalid_parameter`
message	String	Informative message describing the error

Assign a Role to a User

Assigns the given role to the specified user.

Request

Method	URL
GET	/api/integration/v2/users/{user_id}/roles

Key	Value	Type	Description
user_id	Integer	URL	The user identifier
name	String	Body	The 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

Key	Value	Description
response_code	String	`not_found`
message	String	More information about the response

Not Found: HTTP 404 example

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

Invalid Parameter

Key	Value	Description
response_code	String	Code indicating type of error. e.g. `invalid_parameter`
message	String	Informative message describing the error

Unassign a Role from a User

Removes the given role from the specified user.

Request

Method	URL
DELETE	/api/integration/v2/users/{user_id}/roles/{name}

Key	Value	Type	Description
user_id	Integer	URL	The user identifier
name	String	URL	The 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

Key	Value	Description
response_code	String	`not_found`
message	String	More information about the response

Not Found: HTTP 404 example

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

Invalid Parameter

Key	Value	Description
response_code	String	Code indicating type of error. e.g. `invalid_parameter`
message	String	Informative message describing the error

In this section:

Object Management API

Authenticating to the API

Sample request

Note

Sample response

Response overview

HTTP status codes

Response body

User Management

Get User Info

Request

Response

Successful response

Successful response example

Unsuccessful response

Create New User

Request

Sample request

Response

Successful response

Successful response sample

Update Existing User

Request

Sample request

Response

Successful response

Unsuccessful response

Offboard User

Request

Sample requests

Response

Successful response

Unsuccessful response

Role Management

List All Roles

Request

Response

Successful response

Successful response example

List Roles Assigned to a User

Request

Response

Successful response

Successful response example

Unsuccessful response

List Users With an Assigned Role

Request

Response

Successful response example

Unsuccessful response

Assign a Role to a User

Request

Sample request

Response

Successful response

Unsuccessful response

Unassign a Role from a User

Request

Response

Successful response

Unsuccessful response

Search results