REST User

Two types of users may be provisioned in Phantom, "automation" users and "normal" users. Automation users are excluded from general user queries by default. To include automation users you can either use a filter /rest/ph_user?_filter_type__in=["normal", "automation"] or as a convenience, use the GET parameter include_automation, for example: /rest/ph_user?include_automation.

/rest/ph_user

Manage users.

Syntax

https://<username>:<password>@<host>/rest/ph_user

POST

Create users.

The body of the request is a JSON object with the following fields.

Field	Required	Type	Description
add_roles	optional	JSON Array	An array of integers that are role IDs or role names. Must be only role ids or only exact role names. New roles to be added to the existing set of roles for the user. (Used to update a record.)
allowed_ips	optional	JSON Array	A whitelist of IPs (CIDR netmask allowed) for automation/service accounts to restrict Phantom server access with the associated token. Default is an empty list, or no access.
default_label	optional	string	The default label to apply to containers created by an automation user. Only applies to automation/service accounts.
default_tenant_id	optional	integer	The default tenant to apply to containers created by an automation user. Only applies to automation/service accounts. Is overridden by the asset's tenant id or an explicit tenant id.
email	optional	string	Use this field if the username is not an email address or the user should be contacted at an email address that is different than the username. If this field does not contain a valid email address, the user will not receive email notifications.
first_name	optional	string	User's given name.
type	optional	string	The type of authentication to confirm user identity, "normal" (used for local users), "ldap", "openid", or "saml2".
last_name	optional	string	User's family name.
location	optional	string	Physical location of th user. Usually an office or city location.
password	optional	string	Password for the user in clear text (communication happens over HTTPS for security). This field is required when creating a non-AD user. Otherwise is optional. Cannot be used on an AD user.
remove_roles	optional	JSON Array	An array of integers that are role IDs or role names. Must be only role ids or only exact role names. List of roles to be removed from the existing set of roles for the user. (Used to update a record.)
roles	optional	JSON Array	Array of integers that are role IDs or role names. Must be only role ids or only exact role names. This sets or completely replaces the user's roles. Overrides add_roles and remove_roles.
time_zone	optional	string	Time zone user works in. See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for a list of time zones.
title	optional	string	User's title.
type	optional	string	Set to "automation" when creating a automation/service account. Can only be set when creating a user, ignored on update.
username	required	string	User's login name.
2fa	optional	string	String indicating two factor authentication for the user. Currently the only valid values for this are "duo" and null.
2fa_username	optional	string	Username to use for 2FA if not using the user's username.

Example request
Create a standard user.

curl -k -u admin:changeme https://localhost/rest/ph_user \
-d '{
    "username": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "title": "Automation Engineer",
    "location": "Palo Alto",
    "time_zone": "US/Pacific",
    "password": "cleartextpassword",
    "roles": [8, 14, 23],
    "2fa": "duo",
    "2fa_username": "johndoe"
}'

Example request
Create an automation/service user. Fewer fields are required for this type of user.

curl -k -u admin:changeme https://localhost/rest/ph_user \
-d '{
    "allowed_ips": ["10.10.0.0/16"],
    "username": "service_account",
    "roles": ["Automation"],
    "type": "automation"
}'

Example request
Create an LDAP user. Fewer fields are required for this type of user.

curl -k -u admin:changeme https://localhost/rest/ph_user \
-d '{

    "username": "john.doe@example.com",
    "email": "john.doe@example.com",
    "time_zone": "US/Pacific",
    "type": "ldap",
    "roles": [8, 14, 23],
    "2fa": "duo",
    "2fa_username": "johndoe"
}'

Example response
A successful response includes the numeric Id given to the user.

{
    "id": 34,
    "success": true
}

GET

Retrieve user data.

Example request
Retrieve user data. If no user Id is provided a list of users will be returned.

curl -k -u admin:changeme https://localhost/rest/ph_user -G -X GET

Example response
A successful GET will return back a JSON formatted list of key names and data.

{
    "count": 2,
    "data": [
        {
            "username": "george.tailor@splunk.com",
            "first_name": "George",
            "last_name": "Tailor",
            "roles": [],
            "title": null,
            "prevent_login": false,
            "is_active": true,
            "time_zone": null,
            "email": "george.tailor@splunk.com",
            "is_superuser": false,
            "is_staff": false,
            "last_login": null,
            "location": null,
            "default_label": null,
            "default_tenant": null,
            "type": "normal",
            "id": 8,
            "date_joined": "2017-07-29T00:44:39.951851Z"
        },
        {
            "username": "automation",
            "first_name": "",
            "last_name": "",
            "allowed_ips": ["127.0.0.1"],
            "roles": ["Automation"],
            "title": null,
            "prevent_login": false,
            "is_active": true,
            "time_zone": "UTC",
            "email": "",
            "is_superuser": false,
            "is_staff": false,
            "last_login": "2017-08-07T21:14:25.910672Z",
            "location": null,
            "default_label": "events",
            "default_tenant": 0,
            "type": "automation",
            "id": 4,
            "date_joined": "2017-07-29T00:44:40.131816Z"
          },
    ],
    "num_pages": 1
}

/rest/ph_user/<userid>

Manage a user.

Syntax

https://<username>:<password>@<host>/rest/ph_user/<userid>

GET

Retrieve user data for one user.

Example request
Retrieve user data for user Id 1.

curl -k -u admin:changeme https://localhost/rest/ph_user/1 -G -X GET

Example response
A successful GET will return back a JSON formatted list of key names and data.

{
	"last_name": "",
	"is_staff": true,
	"external_update_needed": false,
	"default_label": null,
	"id": 1,
	"date_joined": "2019-11-13T22:50:37.397186Z",
	"first_name": "",
	"title": null,
	"default_tenant": null,
	"is_superuser": true,
	"last_login": "2019-11-18T21:13:41.220935Z",
	"location": null,
	"type": "normal",
	"email": "root@localhost",
	"username": "admin",
	"prevent_login": false,
	"is_active": true,
	"onboarding_state": {
		"redirect_onboarding": false
	},
	"externally_managed": false,
	"roles": ["Administrator"],
	"time_zone": "UTC",
	"show_onboarding": false
}

POST

Update an existing user.

The body of the request is a JSON object with the same fields as /rest/ph_user plus the following optional fields for convenience.

Field	Required	Type	Description
add_roles	optional	array	The Id of the role to add, based on /rest/role.
remove_roles	optional	array	The Id of the role to remove, based on /rest/role.

Example request
Add and remove roles for user Id 1.

curl -k -u admin:changeme https://localhost/rest/ph_user/1 \
-d '{
    "add_roles": [6],
    "remove_roles": [8, 14]
}'

/rest/ph_user/<userid>/token

Get token information.

Syntax

https://<username>:<password>@<host>/rest/ph_user/:id/<token>

GET

Retrieve information about your token. This endpoint is only accessible to automation users, and can only be used to get information for your own token.

Example request
Retrieve token data for a user ID.

curl -k -u soar_local_admin:changeme https://localhost/rest/ph_user/<userid>/token -G -X GET

Example response
A successful GET will return back a JSON formatted list of key names and data.

{
    "id": 1,
    "key": "this-is-a-token",
    "allowed_ips": ["any"],
    "expires_on": "1970-01-01T00:00:00.000000"
}