Skip to main content

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 Arculix 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 Arculix

client_secret

String

The client secret for the application in Arculix

scope

String

A space-delimited list of scopes to be issued to the access token

Sample request

{
   "grant_type": "client_credentials",
   "client_id": "YOUR_ARCULIX_APPLICATION_UID",
   "client_secret": "YOUR_ARCULIX_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@example.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@example.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@example.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@example.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:

  1. Account lock. The user's Arculix 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 Arculix, 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 Arculix Mobile 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 Arculix. 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 Arculix 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 Arculix 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

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@example.com"
        }
    ]
}

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

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

Offboarding multiple users and soft deleting one:

{
    "users": [
        {
            "email": "abe.lincoln@example.com"
        },
        {
            "email": "mark.twain@example.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@example.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@example.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@example.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