na-user API Reference

The na-user service is a simple headless REST solution for managing user records, groups, and attached key/value user data.

Virtually every online service needs to keep track of user data. The na-user service is a solution for the vast majority of those use cases. It allows your developers to focus on on your core business needs and avoid reinventing the wheel.

At its core na-user provides a simple REST API for maintaining a database of users and their commonly required metadata. You can add, delete, update, list, and search users, as well as assign them to groups.

In addition you can use the API to create arbitrary key/value data and attach them to each user.

In a nutshell na-user abstracts away the details of creating and maintaining a user database allowing you to focus on writing your business code without reinventing the wheel of user management.

na-user Home and User Guide: https://nulladmin.com/na-user/

Users

The User Object

An example JSON user object with all fields shown:

 {
    "banned": false,
    "birthdate": "1970-01-01",
    "country": "Luxembourg",
    "create_time": "2017-08-05T15:18:27Z",
    "disabled": false,
    "domain": "premium_users",
    "email": "bong6928@yahoo.com",
    "email_verified": false,
    "family_name": "Reeves",
    "gender": "Other",
    "given_name": "Chantell",
    "locale": "en_US.UTF-8",
    "locality": "Prichard",
    "locked": false,
    "middle_name": "Jeannetta",
    "nickname": "",
    "organization": "Research & Development",
    "phone_number": "(468) 555-1234",
    "phone_number_verified": false,
    "picture_url": "https://placehold.it/400x300",
    "postal_code": "85804",
    "profile_url": "https://facebook.com/bee-2920",
    "region": "Alabama",
    "street_address": "869 Ord Heights",
    "timezone": "Etc/UTC",
    "uid": "9912fbc81691482c814ad1b5b2b6cbeb",
    "update_time": "2017-08-05T15:18:27Z",
    "username": "raeann3286",
    "website_url": "https://www.lanita_4822.net"
  }

The na-user user object is a JSON structure with the following fields:

Note that the update_time and create_time fields are assigned and managed by the system and can't be set via API calls.

Note that password field is never returned in API calls. It can only be set at user creation time or with the /auth/password API call.

Field Name	Field Type	Max Length	Notes
uid	string	36	unique random user identifier, if not provided it is autogenerated
username	string	191	unique user name, can be an email address
password	string	191	optional password, if not set only admin can update the user record
domain	string	191	domain or realm the user belongs to, useful for segmenting users
given_name	string	80
family_name	string	80
middle_name	string	80
nickname	string	80	useful for display purposes instead of the login username
email	string	191	email address
email_verified	boolean	-	true or false, useful for keeping track of verification status
gender	string	80
birthdate	string	10	RFC 3339 full-date format, example: 1970-01-01
timezone	string	80	string in the standard Linux tz database 'Area/Location' format
locale	string	40	best practice is to use POSIX locale strings, but this is not checked
phone_number	string	80
phone_number_varified	boolean	-	true or false, useful for keeping track of verification status
street_address	string	191
locality	string	191	usually this is a city, but not always
region	string	191	usually a state or province
postal_code	string	191
country	string	191
organization	string	191
profile_url	string	191
picture_url	string	191
website_url	string	191
locked	boolean	-
banned	boolean	-
disabled	boolean	-
update_time	string	30	RFC 3339 time-date format. Example: 2017-04-05T15:18:27Z
create_time	string	30	RFC 3339 time-date format. Example: 2017-04-05T15:18:27Z

Create User

POST https://na-user.example.com/users/create

Create a user object. A username is required, all other fields of the user object can also be set but are optional.

If a password is not provided it is set to the blank string, and can be later set using the /auth/password/set API call. Authentication is disabled for users with a blank password.

Users are uniquely identified by a uid. By default the server will assign a unique uid to the new user and return it in the response.

You can optionally set the uid when creating the user. This is useful when you are importing users from another system and want to preserve existing unique identifiers.

A uid is immutable and once created can't be changed via the REST API other then by deleting and re-creating the user.

The format of the system generated uid can be set in the server config file. You can choose the uid to be a UUID, a ULID, or a random hex string.

Notice that the ampersand is urlencoded in the organization field in the example to the left. Without the encoding the input would be cut off after organization=Research string. This is a frequent bug when using cURL to submit forms using the curl -d option.

Minimal required fields to create a user

curl -k -s -X 'POST' -d "username=testuser" \
                     https://na-user.example.com/users/create

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  },
  "result": {
    "uid": "4ed040f052923f2eb6ff731dc7b0fa94"
  }
}

Create a user with all fields set at creation time

curl -k -s -X 'POST' -d "username=testuser" \
                     -d "uid=9912fbc81691482c814ad1b5b2b6cbeb"  \
                     -d "password=supersecret123"  \
                     -d "banned=false"  \
                     -d "birthdate=1970-01-01"  \
                     -d "country=Luxembourg"  \
                     -d "disabled=false"  \
                     -d "domain=premium_users"  \
                     -d "email=bong6928@yahoo.com"  \
                     -d "email_verified=false"  \
                     -d "family_name=Reeves"  \
                     -d "gender=Other"  \
                     -d "given_name=Chantell"  \
                     -d "locale=en_US.UTF-8"  \
                     -d "locality=Prichard"  \
                     -d "locked=false"  \
                     -d "middle_name=Jeannetta"  \
                     -d "nickname=chantell123"  \
                     -d "organization=Research %26 Development"  \
                     -d "phone_number=(468) 059-9066"  \
                     -d "phone_number_verified=false"  \
                     -d "picture_url=https://placehold.it/400x300"  \
                     -d "postal_code=85804"  \
                     -d "profile_url=https://facebook.com/bee-2920"  \
                     -d "region=Wallonia"  \
                     -d "street_address=869 Ord Heights"  \
                     -d "timezone=Etc/UTC"  \
                     -d "username=raeann3286"  \
                     -d "website_url=https://www.lanita_4822.net"  \
                     https://na-user.example.com/users/create

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  },
  "result": {
    "uid": "9912fbc81691482c814ad1b5b2b6cbeb"
  }
}

Get User

Get user

curl -k -s 'https://na-user.example.com/users/get/9912fbc81691482c814ad1b5b2b6cbeb

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  },
  "result": {
    "banned": false,
    "birthdate": "1970-01-01",
    "country": "Luxembourg",
    "create_time": "2017-08-22T15:42:45Z",
    "disabled": false,
    "domain": "premium_users",
    "email": "bong6928@yahoo.com",
    "email_verified": false,
    "family_name": "Reeves",
    "gender": "Other",
    "given_name": "Chantell",
    "locale": "en_US.UTF-8",
    "locality": "Prichard",
    "locked": false,
    "middle_name": "Jeannetta",
    "nickname": "chantell123",
    "organization": "Research & Development",
    "phone_number": "(468) 555-1234",
    "phone_number_verified": false,
    "picture_url": "https://placehold.it/400x300",
    "postal_code": "85804",
    "profile_url": "https://facebook.com/bee-2920",
    "region": "Wallonia",
    "street_address": "869 Ord Heights",
    "timezone": "Etc/UTC",
    "uid": "9912fbc81691482c814ad1b5b2b6cbeb",
    "update_time": "2017-08-22T15:42:45Z",
    "username": "raeann3286",
    "website_url": "https://www.lanita_4822.net"
  }
}

GET https://na-user.example.com/users/get/:uid

Get the a specific user object identified by the uid. Returns all user fields.

If the user is not found HTTP status code 404 Not Found is returned.

Update User

Update all user fields

curl -k -s -X 'POST' -d "username=Raeann3286"  \
                     -d "banned=false"  \
                     -d "birthdate=1970-01-01"  \
                     -d "country=United States"  \
                     -d "disabled=false"  \
                     -d "domain=premium_users"  \
                     -d "email=bong6928@yahoo.com"  \
                     -d "email_verified=true"  \
                     -d "family_name=Reeves"  \
                     -d "gender=Other"  \
                     -d "given_name=Chantell"  \
                     -d "locale=en_US.UTF-8"  \
                     -d "locality=Evanston"  \
                     -d "locked=false"  \
                     -d "middle_name=Jeannetta"  \
                     -d "nickname=chantell123"  \
                     -d "organization=Research %26 Development"  \
                     -d "phone_number=(468) 555-1234"  \
                     -d "phone_number_verified=false"  \
                     -d "picture_url=https://placehold.it/400x300"  \
                     -d "postal_code=60201"  \
                     -d "profile_url=https://facebook.com/bee-2920"  \
                     -d "region=Illinois"  \
                     -d "street_address=869 Ord Heights"  \
                     -d "timezone=Etc/UTC"  \
                     -d "website_url=https://www.lanita_4822.net"  \
                     https://na-user.example.com/users/update/9912fbc81691482c814ad1b5b2b6cbeb

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

POST https://na-user.example.com/users/update/:uid

Update the user object. All fields can be updated with the following exceptions: uid, password, update_time, create_time.

The create_time and update_time fields are automatically maintained by the system. The uid can only be set at user creation time and is immutable.

Exists User

Check if user exists

curl -k -s 'https://na-user.example.com/users/exists/9912fbc81691482c814ad1b5b2b6cbeb

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  },
  "result": {
    "exists": true
  }
}

GET https://na-user.example.com/users/exists/:uid

Checks for the existance of the user object with the given uid. Returns a JSON boolean 'true' or 'false'.

Delete User

Delete user

curl -k -s 'https://na-user.example.com/users/delete/9912fbc81691482c814ad1b5b2b6cbeb'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

DELETE https://na-user.example.com/users/delete/:uid

Delete the user object identified by the uid.

The user delete API call will always return an OK response with HTTP status 200 OK even if the user object did not exist.

List Users

List user objects with default settings. Returns default_page_size objects, with the value of all fields for each user.

curl -k -s 'https://na-user.example.com/users/list'

List user objects with page size and sort parameters, and return only a limited set of fields

curl -k -s -G -d "page_size=3" \
              -d "sort_order=asc" \
              -d "order_by=email" \
              -d "fields=uid,username,email,family_name" \
                 'https://na-user.example.com/users/list'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "d6Uz7S7glG2_-gx38nQCNw4jz9xeWoulIjysWAnJ2FYupzo3I2-gvRiPckbj_E6DqF-NlmI5Wg",
    "prev_pg_token": "Jlr0gKNrGpx2FqLLhhpnDq6HaAfjLY0yvODe2HxCqee4moEWL4SULJ9wPW12jymWOvLjD6IFaw"
  },
  "result": [
    {
      "email": "alica8098@live.com",
      "family_name": "Vasquez",
      "uid": "2e034bf72c114ef482886f23b86611a2",
      "username": "anisa-194"
    },
    {
      "email": "alita8470@gmail.com",
      "family_name": "Sanford",
      "uid": "c449a71694944fdb8fa536f63ebdb7e7",
      "username": "nana7706"
    },
    {
      "email": "alix-6714@live.com",
      "family_name": "Vazquez",
      "uid": "cdf501c9c9d34d60a6f20191ace90b20",
      "username": "tyisha_2929"
    }
  ]
}

The first call will return next_pg_token and prev_pg_token. To get the next (previous) page of results use the returned next_pg_token (prev_pg_token)

curl -k -s -G -d "next_pg_token=d6Uz7S7glG2_-gx38nQCNw4jz9xeWoulIjysWAnJ2FYupzo3I2-gvRiPckbj_E6DqF-NlmI5Wg" \
                 'https://na-user.example.com/users/list'

GET https://na-user.example.com/users/list

List user objects.

The user list API also supports the following optional fields to control the fields returned, sort order, and paging.

Optional user list URL arguments:

Argument	Value
fields	Comma separated list of fields which should be returned. Example: `uid,username,family_name,email`
sort_order	Values can be `asc` for ascending or `desc` for descending sort order
order_by	Results can be ordered by: `username` (default),`uid`,`email`,`family_name`,`create_time`,`update_time`
page_size	Return this many objects rather then the default, subject to `max_page_size` settings in the server config file.
next_pg_token	Continuation token for the next page of listing results
prev_pg_token	Continuation token for the previous page of listing results

Search Users

Search for users with family_name of Lambert, return only certain fields:

curl -k -s -X 'POST' -d "family_name=Lambert" \
                        "fields=username,given_name,middle_name,family_name" \
                        'https://na-user.example.com/users/search'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "K3sOHJH901iOcBbmbc4zHXyuQkjAkJHixlT3rlc6ROJ-XtquPMSXSjf30CtDacaVDFY",
    "prev_pg_token": "UICRfQrKi7D66i7xRyS7n9-wv1BTKJ_xvfLCd0_r7au6Fd_9OGs3UOT8pJM5Dmq1llZJvgAq"
  },
  "result": [
    {
      "family_name": "Lambert",
      "given_name": "Jolie",
      "middle_name": "Celena",
      "username": "catherina-7592"
    },
    {
      "family_name": "Lambert",
      "given_name": "Barbera",
      "middle_name": "Adena",
      "username": "cleora3822"
    }
  ]
}

Search for users with family_name starting with the characters La, returning only two fields. Note the urlencoded % sign indicating matching 0 or more characters to the end of the string.

curl -k -s -X 'POST' -d "family_name=La%25" \
                        "fields=create_time,family_name" \
                        'https://na-user.example.com/users/search'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "5zDGdDuZCUukE4K_K7rjyAC4uE47BRR9LcEMlx_ZFrHcpanWYu71H-2c2Z35U41ocZNKih_3W1e-YNhLFtTZkA",
    "prev_pg_token": "KEgwhtSpOcU40_LiWJwa4nI50gmA7UT2JA754R7j-3_HlW5TUJNLvMlAHQiZ7Y_-WCnrPL3Gjj_VytuHbsCd"
  },
  "result": [
    {
      "create_time": "2017-02-21T07:44:33Z",
      "family_name": "Lambert"
    },
    {
      "create_time": "2017-02-20T12:30:12Z",
      "family_name": "Langley"
    },
    {
      "create_time": "2017-02-22T13:21:07Z",
      "family_name": "Lambert"
    },
    {
      "create_time": "2017-02-24T12:47:45Z",
      "family_name": "Larson"
    }
  ]
}

POST https://na-user.example.com/users/search

Search user objects. Search on certain text, time, and boolean fields is supported.

Specifying multiple search fields returns user objects matching the logical AND of the search terms.

By default the returned objects are ordered by the first field specified in the API call.

Search is case insensitive.

See the Search Users Examples section below for more complex queries.

Searching User Text Fields

You can search on the following text fields:

uid
username
email
phone_number
family_name
organization

Search strings are treated as substrings delimited by the special character % percent sign (%25 urlencoded), which matches any number of characters, even zero:

username=name123 would match the exact username name123,
username=name% would match any username beginning with the characters name
username=%name would match any username ending with the characters name.
username=%name% would match any username containing the substring name.

Searching User Time Fields

You can search the user object create_time and update_time fields. Time fields must be specified in RFC 3339 time-date format. Example: create_time_after=2017-04-05T15:18:27Z

The following are valid time field arguments:

create_time
create_time_after
create_time_before
update_time
update_time_after
update_time_before

Searching Boolean Fields

You can search the following boolean fields by specifying true or false. For example to find all users in the locked state specify locked=true.

locked
banned
disabled

Fields, Sort Order, and Paging

The user search API also supports the following optional fields to control the fields returned, sort order, and paging.

Argument	Value
fields	Comma separated list of fields which should be returned. Example: `uid,username,family_name,email`
	By default the returned objects are ordered by the first field specified in the API call.
sort_order	Values can be `asc` for ascending or `desc` for descending sort order
page_size	Return this many objects rather then the default, subject to `max_page_size` settings in the server config file.
next_pg_token	Continuation token for the next page of listing results
prev_pg_token	Continuation token for the previous page of listing results

Search Users Examples

Example 1: Search for a user with email of testuser@example.com, return all fields:

curl -k -s -X 'POST' -d "email=testuser@example.com" \
                     'https://na-user.example.com/users/search'

Example 2: Search users who have the substring test in their username, return all fields:

curl -k -s -X 'POST' -d "username=%25test%25" \
                     'https://na-user.example.com/users/search'

Example 3: Search users created on 2017-04-05, return all fields.

Note that to include users created on 2017-04-05T00:00:00Z and on 2017-04-05T23:59:59Z we have to make sure our query spans those times with careful use of create_time_after and create_time_before values.

curl -k -s -X 'POST' -d "create_time_after=2017-04-04T23:59:59Z" \
                     -d "create_time_before=2017-04-06T00:00:00Z" \
                     'https://na-user.example.com/users/search'

Example 4: Search users who have the locked flag set with email in the example.com domain, return uid, username, email, and update_time fields:

curl -k -s -X 'POST' -d "email=%25@example.com" \
                     -d "locked=true" \
                     -d "fields=uid,username,email,update_time" \
                     'https://na-user.example.com/users/search'

Add a Policy to a User

Add a policy to a user object

curl -k -s -X 'PUT' 'https://na-user.example.com/users/addpolicy/cdf501c9c9d34d60a6f20191ace90b20/0269f5580e24d4191358611a9551228e'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

PUT https://na-user.exemple.com/users/addpolicy/:uid/:pid

Adds a previously created policy to an existing user object.

If either the policy PID or user UID does not exist HTTP status code 404 Not Found is returned.

List Policies Bound to User

List policies bound to user object

curl -k -s -X 'GET' 'https://na-user.example.com/users/listpolicies/cdf501c9c9d34d60a6f20191ace90b20`

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "mSKVWNKOKejVZIyT1jlO8GRwhD0OfFEfZ5Gr6NXvUYvxoDWq4WxA-yNjO2GPGMpD4gPA",
    "prev_pg_token": "0tXn3xuiwO3jD2bzB_dKHxASD9QpCCHw9UrhvaZRB3tZI16NpsbyUZkTbgKmF8o6qFP0"
  },
  "result": [
    {
      "create_time": "2017-04-29T21:11:17Z",
      "description": "This is policy 09",
      "name": "policy_09",
      "pid": "pid_09",
      "update_time": "2017-04-29T21:11:17Z"
    },
    {
      "create_time": "2017-04-29T21:11:17Z",
      "description": "This is policy 05",
      "name": "policy_05",
      "pid": "pid_05",
      "update_time": "2017-04-29T21:11:17Z"
    },
    {
      "create_time": "2017-04-29T21:11:17Z",
      "description": "This is policy 03",
      "name": "policy_03",
      "pid": "pid_03",
      "update_time": "2017-04-29T21:11:17Z"
    }
  ]
}

GET https://na-user.example.com/users/listpolicies/:uid

List policies bound to user object with page size and sort parameters, and return only a limited set of fields

curl -k -s -G -d "page_size=2" \
              -d "sort_order=asc" \
              -d "fields=pid,name,create_time" \
                 'https://na-user.example.com/users/listpolicies/cdf501c9c9d34d60a6f20191ace90b20'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "ve8dZ6VUxvsBpabMG-g90FINHVDzkjdnyVP6iuPN-srnN7wbnfPSDmYtnCQxt4xcM0ZA",
    "prev_pg_token": "EWGNsr5slQ9dAUbMRtdqeE7Ocivp0zDAQouhnPqeERsB9_wZuA5chg7P92JRWX2p-OaT"
  },
  "result": [
    {
      "create_time": "2017-08-29T21:10:13Z",
      "name": "policy_01",
      "pid": "0fe6c3c7189eff371c20cb09f783413a"
    },
    {
      "create_time": "2017-08-29T21:11:17Z",
      "name": "policy_02",
      "pid": "402df259dc7289d792d39a253fecd353"
    }
  ]
}

Lists the policies which have been added to the user object. The returned list is always ordered by policy create_time.

The policy list API also supports the following optional fields to control the fields returned, sort order, and paging.

Optional policy list URL arguments:

Argument	Value
fields	Comma separated list of fields which should be returned. Example: `pid,name,create_time`
sort_order	Values can be `asc` for ascending or `desc` for descending sort order
page_size	Return this many objects rather then the default, subject to `max_page_size` settings in the server config file.
next_pg_token	Continuation token for the next page of listing results
prev_pg_token	Continuation token for the previous page of listing results

Delete a Policy from User

Deleta a policy from a user object

curl -k -s -X 'DELETE' 'https://na-user.example.com/users/delpolicy/cdf501c9c9d34d60a6f20191ace90b20/0269f5580e24d4191358611a9551228e'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

DELETE https://na-user.exemple.com/users/delpolicy/:uid/:pid

Removes a policy from an existing user object. The policy is not deleted, it is simply unbound from the user object.

This API call always returns success, even if the user UID or policy PID does not exist.

User Passwords

The na-user service can be used by external business logic to authenticate users with common userid/password authentication.

This is in a sense a legacy feature and modern deployments may wish to use other tools to authenticate users, for example using WebAuthn or OAuth.

If you wish to use userid/password authentication then you can set a user's password using the /auth/password/set API call.

Note that the password can also be set at the time the user is created.

Password Set

POST https://na-user.example.com/auth/password/set

Sets the password for the user identified by the username or uid. If both are provided the uid is used to identify the user.

Set a password for user with username 'testuser'

curl -k -s -X 'POST' -d "username=testuser" \
                     -d "password=supersecret" \
                     https://na-user.example.com/auth/password/set

Set a password for user with uid '4ed040f052923f2eb6ff731dc7b0fa94'

curl -k -s -X 'POST' -d "uid=4ed040f052923f2eb6ff731dc7b0fa94" \
                     -d "password=supersecret" \
                     https://na-user.example.com/auth/password/set

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

Groups

The Group Object

An example JSON group object with all fields shown:

{
  "create_time": "2017-08-19T13:43:44Z",
  "description": "Test Group 100",
  "gid": "2c1ac8d338d8198f7d02dc568efcb86e",
  "name": "testgroup100",
  "update_time": "2017-08-19T13:43:44Z"
}

The na-user group object is a JSON structure with the following fields:

Note that the update_time and create_time fields are assigned and managed by the system and can't be set via API calls.

Field Name	Field Type	Max Length	Notes
gid	string	36	unique random group identifier, if not provided it is autogenerated
name	string	80	unique group name
description	string	191	group description string
update_time	string	30	RFC 3339 time-date format. Example: 2017-04-05T15:18:27Z
create_time	string	30	RFC 3339 time-date format. Example: 2017-04-05T15:18:27Z

Create Group

Minimal required fields to create a group

curl -k -s -X 'POST' -d "name=testgroup100" \
                     'https://na-user.example.com/groups/create'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  },
  "result": {
    "gid": "2c1ac8d338d8198f7d02dc568efcb86e"
  }
}

Create a group with all fields set at creation time

curl -k -s -X 'POST' -d "name=testgroup100" \
                     -d "gid=group100" \
                     -d "description=Test Group 100" \
                     'https://na-user.example.com/groups/create'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  },
  "result": {
    "gid": "group100"
  }
}

POST https://na-user.example.com/groups/create

Create a group in the system. A unique group name is required. The gid and description fields of the group object can also be set but are optional.

Groups are uniquely identified by a gid. By default the server will assign a unique gid to the new group and return it in the response.

You can optionally set the gid when creating the group. This is useful when you are importing groups from another system and want to preserve existing unique identifiers.

Get Group

Get group

curl -k -s 'https://na-user.example.com/groups/get/2c1ac8d338d8198f7d02dc568efcb86e'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  },
  "result": {
    "create_time": "2017-08-19T13:43:44Z",
    "description": "Test Group 100",
    "gid": "2c1ac8d338d8198f7d02dc568efcb86e",
    "name": "testgroup100",
    "update_time": "2017-08-19T13:43:44Z"
  }
}

GET https://na-user.example.com/groups/get/:gid

Get the a specific group object identified by the gid. Returns all group fields.

If the group is not found HTTP status code 404 Not Found is returned.

Update Group

Update group fields

curl -k -s -X 'POST' -d "name=new_policy_name"  \
                     -d "description=Updated policy description"  \
                        'https://na-user.example.com/groups/update/0269f5580e24d4191358611a9551228e'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

POST https://na-user.example.com/groups/update/:gid

Update group fields. Only the name and description fields can be updated.

The create_time and update_time fields are automatically maintained by the system.

The gid field can only be set at policy creation time and is immutable.

Exists Group

Check if group exists

curl -k -s 'https://na-user.example.com/groups/exists/2c1ac8d338d8198f7d02dc568efcb86e'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  },
  "result": {
    "exists": true
  }
}

GET https://na-user.example.com/groups/exists/:uid

Checks for the existance of the group object with the given gid. Returns a JSON boolean true or false in the result.

Delete Group

Delete group

curl -k -s -X 'DELETE' 'https://na-user.example.com/groups/delete/2c1ac8d338d8198f7d02dc568efcb86e'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

DELETE https://na-user.example.com/groups/delete/:gid

Delete the group object identified by the gid.

All users assigned to the deleted group will automatically be removed from that group.

The group delete API call will always return an OK response with HTTP status 200 OK even if the group object did not exist.

List Groups

List group objects with default settings. Returns default_page_size objects.

curl -k -s 'https://na-user.example.com/groups/list'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "zolRtoZkOX2dz_I_mcTAig3mmaIUjLRsS1o2w5ZrCl7cryzSNR7WZxc_v8k",
    "prev_pg_token": "0wSvgN4MOMMKM6pMe0zOrz7y1_TmOUKbdNj0oeineU8tgGEPoH4lI0knm38"
  },
  "result": [
    {
      "create_time": "2017-03-24T16:31:10Z",
      "description": "This is group 01",
      "name": "group_01",
      "gid": "27459826d3194eef8e6023c3f05e52df",
      "update_time": "2017-03-24T16:31:10Z"
    },
    {
      "create_time": "2017-03-24T16:31:10Z",
      "description": "This is group 02",
      "name": "group_02",
      "gid": "f8aa9f924c6645afbb86563bfdfda83b",
      "update_time": "2017-03-24T16:31:10Z"
    },
    {
      "create_time": "2017-03-24T16:31:10Z",
      "description": "This is group 03",
      "name": "group_03",
      "gid": "b27aaf81626746248204667e13878b50",
      "update_time": "2017-03-24T16:31:10Z"
    }
  ]
}

List group objects with page size and sort parameters, and only gid and name fields:

curl -k -s -G -d "page_size=2" \
              -d "sort_order=asc" \
              -d "order_by=name" \
              -d "fields=gid,name" \
                 'https://na-user.example.com/groups/list'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "zolRtoZkOX2dz_I_mcTAig3mmaIUjLRsS1o2w5ZrCl7cryzSNR7WZxc_v8k",
    "prev_pg_token": "0wSvgN4MOMMKM6pMe0zOrz7y1_TmOUKbdNj0oeineU8tgGEPoH4lI0knm38"
  },
  "result": [
    {
      "name": "group_01",
      "gid": "27459826d3194eef8e6023c3f05e52df",
    },
    {
      "name": "group_02",
      "gid": "f8aa9f924c6645afbb86563bfdfda83b",
    }
  ]
}

GET https://na-user.example.com/groups/list

List group objects. By default all fields are included in the listing.

Optional group list URL arguments control the returned fields, sort order, and paging:

Argument	Value
fields	Comma separated list of fields which should be returned. Example: `gid,name,description`
sort_order	Values can be `asc` for ascending or `desc` for descending sort order
order_by	Results can be ordered by: `name` (default),`gid`,`description`,`create_time`,`update_time`
page_size	Return this many objects rather then the default, subject to `max_page_size` settings in the server config file.
next_pg_token	Continuation token for the next page of listing results
prev_pg_token	Continuation token for the previous page of listing results

Search Groups

Search for a group with the name group_01, return all fields:

curl -k -s -X 'POST' -d "name=group_01" \
                        'https://na-user.example.com/groups/search'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "PoYEu5Ux88UYT9UX3LVfdZ-0uUoOJmfYDH6SyQf9xkDZI5j6S5Hw4g",
    "prev_pg_token": "x188Z_wuAGa2DDSCcdzgnQ34YYgjvuXE-BAtShUSBLsPznq_tVSyhg"
  },
  "result": [
    {
      "create_time": "2017-08-24T16:31:10Z",
      "description": "This is group 01",
      "name": "group_01",
      "gid": "27459826d3194eef8e6023c3f05e52df",
      "update_time": "2017-08-24T16:31:10Z"
    }
  ]
}

Search for groups with name starting with the characters group_1, returning only two fields. Note the urlencoded % sign indicating matching 0 or more characters to the end of the string.

curl -k -s -X 'POST' -d "name=group_1%25" \
                        "fields=gid,name" \
                        'https://na-user.example.com/groups/search'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "PcJbycY6Z4TjiARLBnjEMDLxJL2FZwAcFaHnB-jrZ0RV__srbiByUww",
    "prev_pg_token": "lQ41D8yjAxVTfUQ3zHcK30GrYP3Zrb3vfOfHoQtBqoFATlzhihbM0FQ"
  },
  "result": [
    {
      "name": "group_10",
      "gid": "602b3cdd16e74ebe9d8af7e7bdbd1624"
    },
    {
      "name": "group_11",
      "gid": "e9ffbe6ba026480d9f84e09df92b7c21"
    }
  ]
}

POST https://na-user.example.com/groups/search

Search group objects. Search on text, and time fields is supported.

Specifying multiple search fields returns user objects matching the logical AND of the search terms.

By default the returned objects are ordered by the first field specified in the API call.

Search is case insensitive.

See the Search Groups Examples section below for more complex queries.

Fields, Sort Order, and Paging

The group search API also supports the following optional fields to control the fields returned, sort order, and paging.

Argument	Value
fields	Comma separated list of fields which should be returned. Example: `gid,name,description`
	By default the returned objects are ordered by the first field specified in the API call.
sort_order	Values can be `asc` for ascending or `desc` for descending sort order
page_size	Return this many objects rather then the default, subject to `max_page_size` settings in the server config file.
next_pg_token	Continuation token for the next page of listing results
prev_pg_token	Continuation token for the previous page of listing results

Searching Group Text Fields

You can search on the following group text fields:

gid
name
description

Search strings are treated as substrings delimited by the special character % percent sign (%25 urlencoded), which matches any number of characters, even zero:

name=p123 would match the exact group name p123
name=p123% would match any group name beginning with the characters p123
name=%p123 would match any group name ending with the characters p123
name=%p123% would match any group name containing the substring p123

Searching Group Time Fields

You can search the group object create_time and update_time fields. Time fields must be specified in RFC 3339 time-date format. Example: create_time_after=2017-04-05T15:18:27Z

The following are valid time field arguments:

create_time
create_time_after
create_time_before
update_time
update_time_after
update_time_before

Search Groups Examples

Example 1: Search for a group with name of group123, return all fields:

curl -k -s -X 'POST' -d "name=group123" \
                     'https://na-user.example.com/groups/search'

Example 2: Search groups which have the substring test in their name, return all fields:

curl -k -s -X 'POST' -d "name=%25test%25" \
                     'https://na-user.example.com/groups/search'

Example 3: Search groups created on 2017-04-05, return all fields.

Note that to include groups created on 2017-04-05T00:00:00Z and on 2017-04-05T23:59:59Z we have to make sure our query spans those times with careful use of create_time_after and create_time_before values.

curl -k -s -X 'POST' -d "create_time_after=2017-04-04T23:59:59Z" \
                     -d "create_time_before=2017-04-06T00:00:00Z" \
                     'https://na-user.example.com/groups/search'

Add User to Group

Add user uid=user1234 to group gid=groupABCD

curl -k -s -X 'PUT' 'https://na-user.example.com/groups/adduser/groupABCD/user1234'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

PUT https://na-user.example.com/groups/adduser/:gid/:uid

Add a user identified by the uid to the group identified by the gid.

If either the group or user is not found, HTTP status 404 Not Found is returned, along with corresponding API status in the body:

{
  "api": {
    "code": "404",
    "message": "Group or user not found"
  }
}

Delete User From Group

Delete user uid=user1234 from group gid=groupABCD

curl -k -s -X 'DELETE' 'https://na-user.example.com/groups/deluser/groupABCD/user1234'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

DELETE https://na-user.example.com/groups/deluser/:gid/:uid

Delete a user identified by the uid from the group identified by the gid.

This API call always returns success even if the group or user do not exist.

List Group Members by `gid`

List users belonging to group identified by gid=groupABCD:

curl -k -s 'https://na-user.example.com/groups/members/gid/groupABCD'

Response:

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "7tjZAmI7w1kG9bkTduzqwRtQHQ4a1-tJ7KGYkHLz5eyuVA-FObvAAdeZT5V-uLp5c0ugH1bInZuPufC6FZg",
    "prev_pg_token": "7T7VUivom02l-o3VIPbEfkccOxCXhAzn2XaRbGZokLvAuvoztQpgg7LsH30-gx5wtgH-99MhyT6g5foKu0A"
  },
  "result": [
    "27459826d3194eef8e6023c3f05e52df",
    "42e92e82c89943f4a7554a18d1f9ad97",
    "7414ce6e7ad9480b8e4f14f5eb7c699a"
  ]
}

GET https://na-user.example.com/groups/members/gid/:gid

List users belonging to the group identified by the gid. The result is a list of uid entries of all users currently part of the group.

Optional list URL arguments control sort order and paging:

Argument	Value
sort_order	Values can be `asc` for ascending or `desc` for descending sort order
page_size	Return this many objects rather then the default, subject to `max_page_size` settings in the server config file.
next_pg_token	Continuation token for the next page of listing results
prev_pg_token	Continuation token for the previous page of listing results

List Group Members by Group `name`

List users belonging to group identified by name=group_name003:

curl -k -s 'https://na-user.example.com/groups/members/groupname/group_name003'

Response:

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "7tjZAmI7w1kG9bkTduzqwRtQHQ4a1-tJ7KGYkHLz5eyuVA-FObvAAdeZT5V-uLp5c0ugH1bInZuPufC6FZg",
    "prev_pg_token": "7T7VUivom02l-o3VIPbEfkccOxCXhAzn2XaRbGZokLvAuvoztQpgg7LsH30-gx5wtgH-99MhyT6g5foKu0A"
  },
  "result": [
    "27459826d3194eef8e6023c3f05e52df",
    "42e92e82c89943f4a7554a18d1f9ad97",
    "7414ce6e7ad9480b8e4f14f5eb7c699a"
  ]
}

GET https://na-user.example.com/groups/members/groupname/:name

List users belonging to the group identified by the group name. The result is a list of uid entries of all users currently part of the group.

Optional list URL arguments control sort order and paging:

Argument	Value
sort_order	Values can be `asc` for ascending or `desc` for descending sort order
page_size	Return this many objects rather then the default, subject to `max_page_size` settings in the server config file.
next_pg_token	Continuation token for the next page of listing results
prev_pg_token	Continuation token for the previous page of listing results

Add a Policy to a Group

Add a policy to a group object

curl -k -s -X 'PUT' 'https://nagroup.example.com/groups/addpolicy/cdf501c9c9d34d60a6f20191ace90b20/0269f5580e24d4191358611a9551228e'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

PUT https://nagroup.exemple.com/groups/addpolicy/:gid/:pid

Adds a previously created policy to an existing group object.

If either the policy PID or group GID does not exist HTTP status code 404 Not Found is returned.

List Policies Bound to Group

List policies bound to group object

curl -k -s -X 'GET' 'https://nagroup.example.com/groups/listpolicies/cdf501c9c9d34d60a6f20191ace90b20`

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "mSKVWNKOKejVZIyT1jlO8GRwhD0OfFEfZ5Gr6NXvUYvxoDWq4WxA-yNjO2GPGMpD4gPA",
    "prev_pg_token": "0tXn3xuiwO3jD2bzB_dKHxASD9QpCCHw9UrhvaZRB3tZI16NpsbyUZkTbgKmF8o6qFP0"
  },
  "result": [
    {
      "create_time": "2017-04-29T21:11:17Z",
      "description": "This is policy 09",
      "name": "policy_09",
      "pid": "pid_09",
      "update_time": "2017-04-29T21:11:17Z"
    },
    {
      "create_time": "2017-04-29T21:11:17Z",
      "description": "This is policy 05",
      "name": "policy_05",
      "pid": "pid_05",
      "update_time": "2017-04-29T21:11:17Z"
    },
    {
      "create_time": "2017-04-29T21:11:17Z",
      "description": "This is policy 03",
      "name": "policy_03",
      "pid": "pid_03",
      "update_time": "2017-04-29T21:11:17Z"
    }
  ]
}

GET https://nagroup.example.com/groups/listpolicies/:gid

List policies bound to group object with page size and sort parameters, and return only a limited set of fields

curl -k -s -G -d "page_size=2" \
              -d "sort_order=asc" \
              -d "fields=pid,name,create_time" \
                 'https://nagroup.example.com/groups/listpolicies/cdf501c9c9d34d60a6f20191ace90b20'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "ve8dZ6VUxvsBpabMG-g90FINHVDzkjdnyVP6iuPN-srnN7wbnfPSDmYtnCQxt4xcM0ZA",
    "prev_pg_token": "EWGNsr5slQ9dAUbMRtdqeE7Ocivp0zDAQouhnPqeERsB9_wZuA5chg7P92JRWX2p-OaT"
  },
  "result": [
    {
      "create_time": "2017-08-29T21:10:13Z",
      "name": "policy_01",
      "pid": "0fe6c3c7189eff371c20cb09f783413a"
    },
    {
      "create_time": "2017-08-29T21:11:17Z",
      "name": "policy_02",
      "pid": "402df259dc7289d792d39a253fecd353"
    }
  ]
}

Lists the policies which have been added to the group object. The returned list is always ordered by policy create_time.

The policy list API also supports the following optional fields to control the fields returned, sort order, and paging.

Optional policy list URL arguments:

Argument	Value
fields	Comma separated list of fields which should be returned. Example: `pid,name,create_time`
sort_order	Values can be `asc` for ascending or `desc` for descending sort order
page_size	Return this many objects rather then the default, subject to `max_page_size` settings in the server config file.
next_pg_token	Continuation token for the next page of listing results
prev_pg_token	Continuation token for the previous page of listing results

Delete a Policy from Group

Deleta a policy from a group object

curl -k -s -X 'DELETE' 'https://nagroup.example.com/groups/delpolicy/cdf501c9c9d34d60a6f20191ace90b20/0269f5580e24d4191358611a9551228e'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

DELETE https://nagroup.exemple.com/groups/delpolicy/:gid/:pid

Removes a policy from an existing group object. The policy is not deleted, it is simply unbound from the group object.

This API call always returns success, even if the group GID or policy PID does not exist.

Keys/Values

The Key/Value Object

An example JSON key value object with all fields shown:

{
  "create_time": "2017-08-19T13:43:44Z",
  "key": "testkey100",
  "value": "TestValue100",
  "uid": "4495a67a2d964599bc827b6acbda623a",
  "update_time": "2017-08-19T13:43:44Z"
}

You can set key/value pairs and associate them with users. Key/values are always associated with a specific user id uid, which must exist in the system when the key is created. There is no pre set limit on the number of key/value pairs created per user. If a user record is deleted, all associated key/value pairs are also automatically deleted.

The na-user key/value object is a JSON structure with the following fields:

Note that the update_time and create_time fields are assigned and managed by the system and can't be set via API calls.

Field Name	Field Type	Max Length	Notes
uid	string	36	the uid of the user to whom the key/value pair belongs
key	string	80	unique key name
value	string	191	key value
update_time	string	30	RFC 3339 time-date format. Example: 2017-04-05T15:18:27Z
create_time	string	30	RFC 3339 time-date format. Example: 2017-04-05T15:18:27Z

Create Key

Create a key/value pair for the user identified by uid=4495a67a2d964599bc827b6acbda623a

curl -k -s -X 'POST' -d "key=testkey100" \
                     -d "value=TestValue100" \
                     -d "uid=4495a67a2d964599bc827b6acbda623a" \
                     'https://na-user.example.com/keys/create'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

POST https://na-user.example.com/keys/create

Create a key/value and associates it with a user record. Requires the uid, key, and value fields.

The uid must already exist before a key/value can be assigned. If the key already exists the call will return HTTP status code 409 Conflict.

Get Key Value

Get key

curl -k -s -X 'POST' -d "key=testkey100" \
                     -d "uid=4495a67a2d964599bc827b6acbda623a" \
                     'https://na-user.example.com/keys/get'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  },
  "result": {
    "create_time": "2017-08-19T13:43:44Z",
    "value": "TestValue100",
    "uid": "4495a67a2d964599bc827b6acbda623a",
    "key": "testkey100",
    "update_time": "2017-08-19T13:43:44Z"
  }
}

POST https://na-user.example.com/keys/get

Get the a specific key/value object identified by the key field and belonging to the user identified by the uid field. Returns all key fields.

If the key is not found HTTP status code 404 Not Found is returned.

Update Key Value

Update value for a given key

curl -k -s -X 'POST' -d "key=testkey100"  \
                     -d "value=updated test value"  \
                     -d "uid=4495a67a2d964599bc827b6acbda623a" \
                     'https://na-user.example.com/keys/update'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

POST https://na-user.example.com/keys/update

Update the value of an existing key. The key, value, and uid fields are required. The update_time field for the key/value object will be automatically updated.

If the key you are trying to updated does not exist the call returns HTTP status 404 - Not Found.

Exists Key

Check if a key exists

curl -k -s -X 'POST' -d "key=testkey100"  \
                     -d "uid=4495a67a2d964599bc827b6acbda623a" \
                     'https://na-user.example.com/keys/exists'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  },
  "result": {
    "exists": true
  }
}

POST https://na-user.example.com/keys/exists

Checks for the existance of the key/value object with the given key name and uid. Returns JSON boolean true or false in the result.

Delete Key

Delete key

curl -k -s -X 'POST' -d "key=testkey100"  \
                     -d "uid=4495a67a2d964599bc827b6acbda623a" \
                     'https://na-user.example.com/keys/delete'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

POST https://na-user.example.com/keys/delete

Delete the key/value object identified by the key belonging to the user identified by the uid.

The key delete API call will always return an OK response with HTTP status 200 OK even if the key object did not exist.

Delete All Keys

Delete all key/value pairs belonging to uid 4495a67a2d964599bc827b6acbda623a

curl -k -s -X 'POST' -d "uid=4495a67a2d964599bc827b6acbda623a" \
                     'https://na-user.example.com/keys/alldelete'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  }
}

POST https://na-user.example.com/keys/alldelete

Deletes all key/value objects belonging to the given uid. Useful if you want to completely clear out the user's key/value space without deleting the user.

This API call will always return an OK response with HTTP status 200 OK even if there were no key/values associated with the given uid, or if the uid did not exist.

List Keys

List key/value objects with default settings for uid=4495a67a2d964599bc827b6acbda623a. Returns default_page_size objects.

curl -k -s 'https://na-user.example.com/keys/list/4495a67a2d964599bc827b6acbda623a'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "zolRtoZkOX2dz_I_mcTAig3mmaIUjLRsS1o2w5ZrCl7cryzSNR7WZxc_v8k",
    "prev_pg_token": "0wSvgN4MOMMKM6pMe0zOrz7y1_TmOUKbdNj0oeineU8tgGEPoH4lI0knm38"
  },
  "result": [
    {
      "create_time": "2017-03-24T16:31:10Z",
      "key": "key_01",
      "value": "This is value 01",
      "uid": "4495a67a2d964599bc827b6acbda623a",
      "update_time": "2017-03-24T16:31:10Z"
    },
    {
      "create_time": "2017-03-24T16:31:10Z",
      "key": "key_02",
      "value": "This is value 02",
      "uid": "4495a67a2d964599bc827b6acbda623a",
      "update_time": "2017-03-24T16:31:10Z"
    },
    {
      "create_time": "2017-03-24T16:31:10Z",
      "key": "key_03",
      "value": "This is value 03",
      "uid": "4495a67a2d964599bc827b6acbda623a",
      "update_time": "2017-03-24T16:31:10Z"
    }
  ]
}

List key objects for uid=4495a67a2d964599bc827b6acbda623a with page size and sort parameters, and only key and value fields:

curl -k -s -G -d "page_size=2" \
              -d "sort_order=asc" \
              -d "order_by=key" \
              -d "fields=key,value" \
              'https://na-user.example.com/keys/list/4495a67a2d964599bc827b6acbda623a'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "zolRtoZkOX2dz_I_mcTAig3mmaIUjLRsS1o2w5ZrCl7cryzSNR7WZxc_v8k",
    "prev_pg_token": "0wSvgN4MOMMKM6pMe0zOrz7y1_TmOUKbdNj0oeineU8tgGEPoH4lI0knm38"
  },
  "result": [
    {
      "key": "key_01",
      "value": "This is value 01",
    },
    {
      "key": "key_02",
      "value": "This is value 02",
    }
  ]
}

GET https://na-user.example.com/keys/list/:uid

List all key/value objects belonging to the uid. By default all fields are included in the listing.

If the uid does not exist the call returns HTTP status 404 - Not Found.

Optional key list URL arguments control the returned fields, sort order, and paging:

Argument	Value
fields	Comma separated list of fields which should be returned. Example: `uid,key,value,create_time`
sort_order	Values can be `asc` for ascending or `desc` for descending sort order
order_by	Results can be ordered by: `key` (default),`value`,`create_time`,`update_time`
page_size	Return this many objects rather then the default, subject to `max_page_size` settings in the server config file.
next_pg_token	Continuation token for the next page of listing results
prev_pg_token	Continuation token for the previous page of listing results

Search Keys and Values

Search for a key with the exact name key_01 for uid=4495a67a2d964599bc827b6acbda623a, return all fields:

curl -k -s -X 'POST' -d "key=key_01" \
                     -d "uid=4495a67a2d964599bc827b6acbda623a" \
                     'https://na-user.example.com/keys/search'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "PoYEu5Ux88UYT9UX3LVfdZ-0uUoOJmfYDH6SyQf9xkDZI5j6S5Hw4g",
    "prev_pg_token": "x188Z_wuAGa2DDSCcdzgnQ34YYgjvuXE-BAtShUSBLsPznq_tVSyhg"
  },
  "result": [
    {
      "create_time": "2017-08-24T16:31:10Z",
      "key": "key_01",
      "value": "This is value 01",
      "uid": "4495a67a2d964599bc827b6acbda623a",
      "update_time": "2017-08-24T16:31:10Z"
    }
  ]
}

Search for keys with name starting with the characters key_1, returning only the key and value fields. Note the urlencoded % sign indicating matching 0 or more characters to the end of the string.

curl -k -s -X 'POST' -d "key=key_1%25" \
                     -d "uid=4495a67a2d964599bc827b6acbda623a" \
                     -d "fields=key,value" \
                     'https://na-user.example.com/keys/search'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "PcJbycY6Z4TjiARLBnjEMDLxJL2FZwAcFaHnB-jrZ0RV__srbiByUww",
    "prev_pg_token": "lQ41D8yjAxVTfUQ3zHcK30GrYP3Zrb3vfOfHoQtBqoFATlzhihbM0FQ"
  },
  "result": [
    {
      "key": "key_1",
      "value": "This is value 01"
    },
    {
      "key": "key_10",
      "value": "This is value 10"
    },
    {
      "key": "key_101",
      "value": "This is value 101"
    }
  ]
}

Search for key/values with the substring value 10 in the value, returning only the key and value fields. Note the urlencoded % signs indicating matching 0 or more characters at the start and the end of the string.

curl -k -s -X 'POST' -d "value=%25value 10%25" \
                     -d "uid=4495a67a2d964599bc827b6acbda623a" \
                     -d "fields=key,value" \
                     'https://na-user.example.com/keys/search'

Response

{
  "api": {
    "code": "0",
    "message": "OK",
    "next_pg_token": "PcJbycY6Z4TjiARLBnjEMDLxJL2FZwAcFaHnB-jrZ0RV__srbiByUww",
    "prev_pg_token": "lQ41D8yjAxVTfUQ3zHcK30GrYP3Zrb3vfOfHoQtBqoFATlzhihbM0FQ"
  },
  "result": [
    {
      "key": "key_10",
      "value": "This is value 10"
    },
    {
      "key": "key_101",
      "value": "This is value 101"
    }
  ]
}

POST https://na-user.example.com/keys/search

Search key/value objects. Search on the key, value, and time fields is supported.

The uid is used to limit the search to only the specified user's keys.

If the uid is omitted, all key/values belonging to all users matching the given search parameters are returned. This is useful to enumerate or count all the different values for a given key in the database.

If the uid is given, but does not exist the call returns HTTP status 404 - Not Found.

Specifying multiple search fields (e.g. both key and value) returns key/value objects matching the logical AND of the search terms.

By default the returned objects are ordered by the first field specified in the API call.

Search is case insensitive.

See the Search Keys Examples section below for more complex queries.

Fields, Sort Order, and Paging

The key search API also supports the following optional fields to control the fields returned, sort order, and paging.

Argument	Value
fields	Comma separated list of fields which should be returned. Example: `key,value,uid,create_time`
	By default the returned objects are ordered by the first field specified in the API call.
sort_order	Values can be `asc` for ascending or `desc` for descending sort order
page_size	Return this many objects rather then the default, subject to `max_page_size` settings in the server config file.
next_pg_token	Continuation token for the next page of listing results
prev_pg_token	Continuation token for the previous page of listing results

Searching Key/Value Text Fields

You can search on the following key/value text fields:

key
value
create_time
update_time

Search strings are treated as substrings delimited by the special character % percent sign (%25 urlencoded), which matches any number of characters, even zero:

key=k123 would match the exact key key k123
key=k123% would match any key beginning with the characters k123
key=%k123 would match any key ending with the characters k123
key=%k123% would match any key containing the substring k123

Searching Key/Value Time Fields

You can search the key object create_time and update_time fields. Time fields must be specified in RFC 3339 time-date format. Example: create_time_after=2017-04-05T15:18:27Z

The following are valid time field arguments:

create_time
create_time_after
create_time_before
update_time
update_time_after
update_time_before

Search Key/Value Examples

Example 1: Search for a key with name of key123, return all fields:

curl -k -s -X 'POST' -d "name=key123" -d "uid=4495a67a2d964599bc827b6acbda623a" 'https://na-user.example.com/keys/search'

Example 2: Search keys which have the substring test in their key name, return all fields:

curl -k -s -X 'POST' -d "name=%25test%25" -d "uid=4495a67a2d964599bc827b6acbda623a" 'https://na-user.example.com/keys/search'

Example 3: Search keys created on 2017-04-05, return all fields.

Note that to include keys created on 2017-04-05T00:00:00Z and on 2017-04-05T23:59:59Z we have to make sure our query spans those times with careful use of create_time_after and create_time_before values.

curl -k -s -X 'POST' -d "create_time_after=2017-04-04T23:59:59Z" -d "create_time_before=2017-04-06T00:00:00Z" -d "uid=4495a67a2d964599bc827b6acbda623a" 'https://na-user.example.com/keys/search'

Metrics

GET https://na-user.example.com/metrics

This API endpoint provides server metrics suitable for scraping by Prometheus.

Metrics endpoint

curl -k -s 'https://na-user.example.com/metrics'

Response

# HELP go_gc_duration_seconds A summary of the GC invocation durations.
# TYPE go_gc_duration_seconds summary
go_gc_duration_seconds{quantile="0"} 0
go_gc_duration_seconds{quantile="0.25"} 0
go_gc_duration_seconds{quantile="0.5"} 0
go_gc_duration_seconds{quantile="0.75"} 0
go_gc_duration_seconds{quantile="1"} 0
go_gc_duration_seconds_sum 0
go_gc_duration_seconds_count 0
# HELP go_goroutines Number of goroutines that currently exist.
# TYPE go_goroutines gauge
go_goroutines 12
# HELP go_info Information about the Go environment.
# TYPE go_info gauge
go_info{version="go1.21.1"} 1
# HELP go_memstats_alloc_bytes Number of bytes allocated and still in use.
# TYPE go_memstats_alloc_bytes gauge
go_memstats_alloc_bytes 1.796928e+06
# HELP go_memstats_alloc_bytes_total Total number of bytes allocated, even if freed.
# TYPE go_memstats_alloc_bytes_total counter
go_memstats_alloc_bytes_total 1.796928e+06
# HELP go_memstats_buck_hash_sys_bytes Number of bytes used by the profiling bucket hash table.
# TYPE go_memstats_buck_hash_sys_bytes gauge
go_memstats_buck_hash_sys_bytes 4483
# HELP go_memstats_frees_total Total number of frees.
# TYPE go_memstats_frees_total counter
go_memstats_frees_total 704
# HELP go_memstats_gc_cpu_fraction The fraction of this program's available CPU time used by the GC since the program started.
# TYPE go_memstats_gc_cpu_fraction gauge
go_memstats_gc_cpu_fraction 0
# HELP go_memstats_gc_sys_bytes Number of bytes used for garbage collection system metadata.
# TYPE go_memstats_gc_sys_bytes gauge
go_memstats_gc_sys_bytes 3.199272e+06
# HELP go_memstats_heap_alloc_bytes Number of heap bytes allocated and still in use.
# TYPE go_memstats_heap_alloc_bytes gauge
go_memstats_heap_alloc_bytes 1.796928e+06
# HELP go_memstats_heap_idle_bytes Number of heap bytes waiting to be used.
# TYPE go_memstats_heap_idle_bytes gauge
go_memstats_heap_idle_bytes 4.497408e+06
# HELP go_memstats_heap_inuse_bytes Number of heap bytes that are in use.
# TYPE go_memstats_heap_inuse_bytes gauge
go_memstats_heap_inuse_bytes 3.268608e+06
# HELP go_memstats_heap_objects Number of allocated objects.
# TYPE go_memstats_heap_objects gauge
go_memstats_heap_objects 12706
# HELP go_memstats_heap_released_bytes Number of heap bytes released to OS.
# TYPE go_memstats_heap_released_bytes gauge
go_memstats_heap_released_bytes 4.46464e+06
# HELP go_memstats_heap_sys_bytes Number of heap bytes obtained from system.
# TYPE go_memstats_heap_sys_bytes gauge
go_memstats_heap_sys_bytes 7.766016e+06
# HELP go_memstats_last_gc_time_seconds Number of seconds since 1970 of last garbage collection.
# TYPE go_memstats_last_gc_time_seconds gauge
go_memstats_last_gc_time_seconds 0
# HELP go_memstats_lookups_total Total number of pointer lookups.
# TYPE go_memstats_lookups_total counter
go_memstats_lookups_total 0
# HELP go_memstats_mallocs_total Total number of mallocs.
# TYPE go_memstats_mallocs_total counter
go_memstats_mallocs_total 13410
# HELP go_memstats_mcache_inuse_bytes Number of bytes in use by mcache structures.
# TYPE go_memstats_mcache_inuse_bytes gauge
go_memstats_mcache_inuse_bytes 4800
# HELP go_memstats_mcache_sys_bytes Number of bytes used for mcache structures obtained from system.
# TYPE go_memstats_mcache_sys_bytes gauge
go_memstats_mcache_sys_bytes 15600
# HELP go_memstats_mspan_inuse_bytes Number of bytes in use by mspan structures.
# TYPE go_memstats_mspan_inuse_bytes gauge
go_memstats_mspan_inuse_bytes 67704
# HELP go_memstats_mspan_sys_bytes Number of bytes used for mspan structures obtained from system.
# TYPE go_memstats_mspan_sys_bytes gauge
go_memstats_mspan_sys_bytes 81480
# HELP go_memstats_next_gc_bytes Number of heap bytes when next garbage collection will take place.
# TYPE go_memstats_next_gc_bytes gauge
go_memstats_next_gc_bytes 4.194304e+06
# HELP go_memstats_other_sys_bytes Number of bytes used for other system allocations.
# TYPE go_memstats_other_sys_bytes gauge
go_memstats_other_sys_bytes 736813
# HELP go_memstats_stack_inuse_bytes Number of bytes in use by the stack allocator.
# TYPE go_memstats_stack_inuse_bytes gauge
go_memstats_stack_inuse_bytes 622592
# HELP go_memstats_stack_sys_bytes Number of bytes obtained from system for stack allocator.
# TYPE go_memstats_stack_sys_bytes gauge
go_memstats_stack_sys_bytes 622592
# HELP go_memstats_sys_bytes Number of bytes obtained from system.
# TYPE go_memstats_sys_bytes gauge
go_memstats_sys_bytes 1.2426256e+07
# HELP go_threads Number of OS threads created.
# TYPE go_threads gauge
go_threads 9
# HELP na_user_http_200_ok_total Number of HTTP Status 200 OK responses
# TYPE na_user_http_200_ok_total counter
na_user_http_200_ok_total 1
# HELP na_user_http_400_bad_request_total Number of HTTP Status 400 BadRequest responses
# TYPE na_user_http_400_bad_request_total counter
na_user_http_400_bad_request_total 0
# HELP na_user_http_401_unauthorized_total Number of HTTP Status 401 Unauthorized responses
# TYPE na_user_http_401_unauthorized_total counter
na_user_http_401_unauthorized_total 0
# HELP na_user_http_403_forbidden_total Number of HTTP Status 403 Forbidden responses
# TYPE na_user_http_403_forbidden_total counter
na_user_http_403_forbidden_total 0
# HELP na_user_http_404_not_found_total Number of HTTP Status 404 NotFound responses
# TYPE na_user_http_404_not_found_total counter
na_user_http_404_not_found_total 0
# HELP na_user_http_405_method_not_allowed_total Number of HTTP Status 405 MethodNotAllowed responses
# TYPE na_user_http_405_method_not_allowed_total counter
na_user_http_405_method_not_allowed_total 0
# HELP na_user_http_409_conflict_total Number of HTTP Status 409 Conflict responses
# TYPE na_user_http_409_conflict_total counter
na_user_http_409_conflict_total 0
# HELP na_user_http_500_internal_server_error_total Number of HTTP Status 500 InternalServerError responses
# TYPE na_user_http_500_internal_server_error_total counter
na_user_http_500_internal_server_error_total 0
# HELP na_user_http_503_service_unavailable_total Number of HTTP Status 503 ServiceUnavailable responses
# TYPE na_user_http_503_service_unavailable_total counter
na_user_http_503_service_unavailable_total 0
# HELP na_user_http_errors_total Number of HTTP Error (non 200) responses
# TYPE na_user_http_errors_total counter
na_user_http_errors_total 0
# HELP na_user_requests_auth_error_total Number of errors during authentication
# TYPE na_user_requests_auth_error_total counter
na_user_requests_auth_error_total 0
# HELP na_user_requests_auth_login_total Number of requests to /auth/login
# TYPE na_user_requests_auth_login_total counter
na_user_requests_auth_login_total 0
# HELP na_user_requests_auth_logout_total Number of requests to /auth/logout
# TYPE na_user_requests_auth_logout_total counter
na_user_requests_auth_logout_total 0
# HELP na_user_requests_auth_password_set_total Number of requests to /auth/password/set
# TYPE na_user_requests_auth_password_set_total counter
na_user_requests_auth_password_set_total 0
# HELP na_user_requests_groups_adduser_total Number of requests to /groups/adduser
# TYPE na_user_requests_groups_adduser_total counter
na_user_requests_groups_adduser_total 0
# HELP na_user_requests_groups_create_total Number of requests to /groups/create
# TYPE na_user_requests_groups_create_total counter
na_user_requests_groups_create_total 0
# HELP na_user_requests_groups_delete_total Number of requests to /groups/delete
# TYPE na_user_requests_groups_delete_total counter
na_user_requests_groups_delete_total 0
# HELP na_user_requests_groups_deluser_total Number of requests to /groups/deluser
# TYPE na_user_requests_groups_deluser_total counter
na_user_requests_groups_deluser_total 0
# HELP na_user_requests_groups_exists_total Number of requests to /groups/exists
# TYPE na_user_requests_groups_exists_total counter
na_user_requests_groups_exists_total 0
# HELP na_user_requests_groups_get_total Number of requests to /groups/get
# TYPE na_user_requests_groups_get_total counter
na_user_requests_groups_get_total 0
# HELP na_user_requests_groups_list_total Number of requests to /groups/list
# TYPE na_user_requests_groups_list_total counter
na_user_requests_groups_list_total 0
# HELP na_user_requests_groups_members_gid_total Number of requests to /groups/members/gid
# TYPE na_user_requests_groups_members_gid_total counter
na_user_requests_groups_members_gid_total 0
# HELP na_user_requests_groups_members_groupname_total Number of requests to /groups/members/groupname
# TYPE na_user_requests_groups_members_groupname_total counter
na_user_requests_groups_members_groupname_total 0
# HELP na_user_requests_groups_policies_add_total Number of PUT requests to /groups/:gid/policies/:pid
# TYPE na_user_requests_groups_policies_add_total counter
na_user_requests_groups_policies_add_total 0
# HELP na_user_requests_groups_policies_del_total Number of DELETE requests to /groups/:gid/policies/:pid
# TYPE na_user_requests_groups_policies_del_total counter
na_user_requests_groups_policies_del_total 0
# HELP na_user_requests_groups_policies_list_total Number of GET requests to /groups/:gid/policies
# TYPE na_user_requests_groups_policies_list_total counter
na_user_requests_groups_policies_list_total 0
# HELP na_user_requests_groups_search_total Number of requests to /groups/search
# TYPE na_user_requests_groups_search_total counter
na_user_requests_groups_search_total 0
# HELP na_user_requests_groups_update_total Number of requests to /groups/update
# TYPE na_user_requests_groups_update_total counter
na_user_requests_groups_update_total 0
# HELP na_user_requests_health_total Number of requests to /health
# TYPE na_user_requests_health_total counter
na_user_requests_health_total 0
# HELP na_user_requests_index_total Number of requests to /
# TYPE na_user_requests_index_total counter
na_user_requests_index_total 0
# HELP na_user_requests_keys_create_total Number of requests to /keys/create
# TYPE na_user_requests_keys_create_total counter
na_user_requests_keys_create_total 0
# HELP na_user_requests_keys_delete_total Number of requests to /keys/delete
# TYPE na_user_requests_keys_delete_total counter
na_user_requests_keys_delete_total 0
# HELP na_user_requests_keys_exists_total Number of requests to /keys/exists
# TYPE na_user_requests_keys_exists_total counter
na_user_requests_keys_exists_total 0
# HELP na_user_requests_keys_get_total Number of requests to /keys/get
# TYPE na_user_requests_keys_get_total counter
na_user_requests_keys_get_total 0
# HELP na_user_requests_keys_list_total Number of requests to /keys/list
# TYPE na_user_requests_keys_list_total counter
na_user_requests_keys_list_total 0
# HELP na_user_requests_keys_search_total Number of requests to /keys/search
# TYPE na_user_requests_keys_search_total counter
na_user_requests_keys_search_total 0
# HELP na_user_requests_keys_update_total Number of requests to /keys/update
# TYPE na_user_requests_keys_update_total counter
na_user_requests_keys_update_total 0
# HELP na_user_requests_metrics_total Number of requests to /metrics
# TYPE na_user_requests_metrics_total counter
na_user_requests_metrics_total 1
# HELP na_user_requests_permissions_create_total Number of POST requests to /permissions/create
# TYPE na_user_requests_permissions_create_total counter
na_user_requests_permissions_create_total 0
# HELP na_user_requests_permissions_delete_total Number of DELETE requests to /permissions/delete
# TYPE na_user_requests_permissions_delete_total counter
na_user_requests_permissions_delete_total 0
# HELP na_user_requests_permissions_exists_total Number of GET requests to /permissions/exists
# TYPE na_user_requests_permissions_exists_total counter
na_user_requests_permissions_exists_total 0
# HELP na_user_requests_permissions_get_total Number of GET requests to /permissions/get
# TYPE na_user_requests_permissions_get_total counter
na_user_requests_permissions_get_total 0
# HELP na_user_requests_permissions_list_total Number of GET requests to /permissions/list
# TYPE na_user_requests_permissions_list_total counter
na_user_requests_permissions_list_total 0
# HELP na_user_requests_permissions_search_total Number of POST requests to /permissions/search
# TYPE na_user_requests_permissions_search_total counter
na_user_requests_permissions_search_total 0
# HELP na_user_requests_permissions_update_total Number of POST requests to /permissions/update
# TYPE na_user_requests_permissions_update_total counter
na_user_requests_permissions_update_total 0
# HELP na_user_requests_policies_create_total Number of POST requests to /policies/create
# TYPE na_user_requests_policies_create_total counter
na_user_requests_policies_create_total 0
# HELP na_user_requests_policies_delete_total Number of DELETE requests to /policies/delete
# TYPE na_user_requests_policies_delete_total counter
na_user_requests_policies_delete_total 0
# HELP na_user_requests_policies_exists_total Number of GET requests to /policies/exists
# TYPE na_user_requests_policies_exists_total counter
na_user_requests_policies_exists_total 0
# HELP na_user_requests_policies_get_total Number of GET requests to /policies/get
# TYPE na_user_requests_policies_get_total counter
na_user_requests_policies_get_total 0
# HELP na_user_requests_policies_list_total Number of GET requests to /policies/list
# TYPE na_user_requests_policies_list_total counter
na_user_requests_policies_list_total 0
# HELP na_user_requests_policies_permissions_add_total Number of PUT requests to /policies/:pid/permissions/:permid
# TYPE na_user_requests_policies_permissions_add_total counter
na_user_requests_policies_permissions_add_total 0
# HELP na_user_requests_policies_permissions_del_total Number of DELETE requests to /policies/:pid/permissions/:permid
# TYPE na_user_requests_policies_permissions_del_total counter
na_user_requests_policies_permissions_del_total 0
# HELP na_user_requests_policies_permissions_list_total Number of GET requests to /policies/:pid/permissions
# TYPE na_user_requests_policies_permissions_list_total counter
na_user_requests_policies_permissions_list_total 0
# HELP na_user_requests_policies_resources_add_total Number of PUT requests to /policies/:pid/resources/:rid
# TYPE na_user_requests_policies_resources_add_total counter
na_user_requests_policies_resources_add_total 0
# HELP na_user_requests_policies_resources_del_total Number of DELETE requests to /policies/:pid/resources/:rid
# TYPE na_user_requests_policies_resources_del_total counter
na_user_requests_policies_resources_del_total 0
# HELP na_user_requests_policies_resources_list_total Number of GET requests to /policies/:pid/resources
# TYPE na_user_requests_policies_resources_list_total counter
na_user_requests_policies_resources_list_total 0
# HELP na_user_requests_policies_search_total Number of POST requests to /policies/search
# TYPE na_user_requests_policies_search_total counter
na_user_requests_policies_search_total 0
# HELP na_user_requests_policies_update_total Number of POST requests to /policies/update
# TYPE na_user_requests_policies_update_total counter
na_user_requests_policies_update_total 0
# HELP na_user_requests_resources_create_total Number of POST requests to /resources/create
# TYPE na_user_requests_resources_create_total counter
na_user_requests_resources_create_total 0
# HELP na_user_requests_resources_delete_total Number of DELETE requests to /resources/delete
# TYPE na_user_requests_resources_delete_total counter
na_user_requests_resources_delete_total 0
# HELP na_user_requests_resources_exists_total Number of GET requests to /resources/exists
# TYPE na_user_requests_resources_exists_total counter
na_user_requests_resources_exists_total 0
# HELP na_user_requests_resources_get_total Number of GET requests to /resources/get
# TYPE na_user_requests_resources_get_total counter
na_user_requests_resources_get_total 0
# HELP na_user_requests_resources_list_total Number of GET requests to /resources/list
# TYPE na_user_requests_resources_list_total counter
na_user_requests_resources_list_total 0
# HELP na_user_requests_resources_search_total Number of POST requests to /resources/search
# TYPE na_user_requests_resources_search_total counter
na_user_requests_resources_search_total 0
# HELP na_user_requests_resources_update_total Number of POST requests to /resources/update
# TYPE na_user_requests_resources_update_total counter
na_user_requests_resources_update_total 0
# HELP na_user_requests_total Total number of API requests
# TYPE na_user_requests_total counter
na_user_requests_total 1
# HELP na_user_requests_users_create_total Number of requests to /users/create
# TYPE na_user_requests_users_create_total counter
na_user_requests_users_create_total 0
# HELP na_user_requests_users_delete_total Number of requests to /users/delete
# TYPE na_user_requests_users_delete_total counter
na_user_requests_users_delete_total 0
# HELP na_user_requests_users_exists_total Number of requests to /users/exists
# TYPE na_user_requests_users_exists_total counter
na_user_requests_users_exists_total 0
# HELP na_user_requests_users_get_total Number of requests to /users/get
# TYPE na_user_requests_users_get_total counter
na_user_requests_users_get_total 0
# HELP na_user_requests_users_list_total Number of requests to /users/list
# TYPE na_user_requests_users_list_total counter
na_user_requests_users_list_total 0
# HELP na_user_requests_users_policies_add_total Number of PUT requests to /users/:uid/policies/:pid
# TYPE na_user_requests_users_policies_add_total counter
na_user_requests_users_policies_add_total 0
# HELP na_user_requests_users_policies_del_total Number of DELETE requests to /users/:uid/policies/:pid
# TYPE na_user_requests_users_policies_del_total counter
na_user_requests_users_policies_del_total 0
# HELP na_user_requests_users_policies_list_total Number of GET requests to /users/:uid/policies
# TYPE na_user_requests_users_policies_list_total counter
na_user_requests_users_policies_list_total 0
# HELP na_user_requests_users_search_total Number of requests to /users/search
# TYPE na_user_requests_users_search_total counter
na_user_requests_users_search_total 0
# HELP na_user_requests_users_update_total Number of requests to /users/update
# TYPE na_user_requests_users_update_total counter
na_user_requests_users_update_total 0
# HELP na_user_requests_version_total Number of requests to /version
# TYPE na_user_requests_version_total counter
na_user_requests_version_total 0
# HELP na_user_response_time_seconds Request response times
# TYPE na_user_response_time_seconds summary
na_user_response_time_seconds{quantile="0.5"} NaN
na_user_response_time_seconds{quantile="0.9"} NaN
na_user_response_time_seconds{quantile="0.99"} NaN
na_user_response_time_seconds_sum 0
na_user_response_time_seconds_count 0
# HELP process_cpu_seconds_total Total user and system CPU time spent in seconds.
# TYPE process_cpu_seconds_total counter
process_cpu_seconds_total 0.22
# HELP process_max_fds Maximum number of open file descriptors.
# TYPE process_max_fds gauge
process_max_fds 1.048576e+06
# HELP process_open_fds Number of open file descriptors.
# TYPE process_open_fds gauge
process_open_fds 10
# HELP process_resident_memory_bytes Resident memory size in bytes.
# TYPE process_resident_memory_bytes gauge
process_resident_memory_bytes 1.2099584e+07
# HELP process_start_time_seconds Start time of the process since unix epoch in seconds.
# TYPE process_start_time_seconds gauge
process_start_time_seconds 1.6977510786e+09
# HELP process_virtual_memory_bytes Virtual memory size in bytes.
# TYPE process_virtual_memory_bytes gauge
process_virtual_memory_bytes 1.268166656e+09
# HELP process_virtual_memory_max_bytes Maximum amount of virtual memory available in bytes.
# TYPE process_virtual_memory_max_bytes gauge
process_virtual_memory_max_bytes -1
# HELP promhttp_metric_handler_requests_in_flight Current number of scrapes being served.
# TYPE promhttp_metric_handler_requests_in_flight gauge
promhttp_metric_handler_requests_in_flight 1
# HELP promhttp_metric_handler_requests_total Total number of scrapes by HTTP status code.
# TYPE promhttp_metric_handler_requests_total counter
promhttp_metric_handler_requests_total{code="200"} 0
promhttp_metric_handler_requests_total{code="500"} 0
promhttp_metric_handler_requests_total{code="503"} 0

Health Status

GET https://na-user.example.com/health

This API endpoint provides output suitable for a simple health monitoring check.

Health check endpoint

curl -k -s 'https://na-user.example.com/health'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  },
  "result": {
    "version": "0.0.1",
    "program": "na-user",
    "revision": "b662a9e",
    "branch": "master",
    "build_date": "2018-03-23T05:31:26Z",
    "go_version": "go1.10",
    "os_arch": "linux/amd64",
    "product_name": "na-user",
    "license_id": "bec10a8e83812ed2b3dbbeba4af06e2b",
    "license_tier": "Standard",
    "license_expire": "2019-05-22T15:55:11-07:00"
  }
}

Server Version

Version endpoint

curl -k -s 'https://na-user.example.com/version'

Response

{
  "api": {
    "code": "0",
    "message": "OK"
  },
  "result": {
    "version": "0.0.1",
    "program": "na-user",
    "revision": "b662a9e",
    "branch": "master",
    "build_date": "2018-03-23T05:31:26Z",
    "go_version": "go1.10",
    "os_arch": "linux/amd64",
    "product_name": "na-user",
    "license_id": "bec10a8e83812ed2b3dbbeba4af06e2b",
    "license_tier": "Standard",
    "license_expire": "2019-05-22T15:55:11-07:00"
  }
}

GET https://na-user.example.com/version

This API endpoint provides server version and license information.

Unicode Support

All na-user API strings support both 3-Byte and 4-Byte UTF-8 Unicode Encoding. This means that you can, for example, use emoji within any field. A username consisting only of the emoji "grinning face with smiling eyes" 😁 (codepoint U+1F601, bytes 0xF09F9881) is perfectly valid.

This may be problematic for certain fields. For example you may not want to allow emoji or 4 byte UTF-8 (as opposed to the more common 3 byte encoding) in usernames. Any system calling the na-user API should filter the input encoding appropriately to its requirements.

JSON Output Encoding

For security reasons JSON output is sanitized by having certain ASCII characters encoded to UTF8 and escaped on output. This encoding allows JSON output to be safely used in HTML <script></script> tags.

Specifically the following encoding is used:

Character	Name	Output Encoding
>	greater than	\u003c
<	less than	\u003e
&	ampersand	\u0026
U+2028	line separator	\u2028
U+2029	paragraph separator	\u2029
"	double quote	\"
\	backslash	\

For example if you submit a string field containing an ASCII encoded greater then symbol (0x3E), then when the field is fetched back through the API the symbol will be encoded as Unicode \u003c in the JSON string.

na-user API Reference

Users

The User Object

Create User

Get User

Update User

Exists User

Delete User

List Users

Search Users

Searching User Text Fields

Searching User Time Fields

Searching Boolean Fields

Fields, Sort Order, and Paging

Search Users Examples

Add a Policy to a User

List Policies Bound to User

Delete a Policy from User

User Passwords

Password Set

Groups

The Group Object

Create Group

Get Group

Update Group

Exists Group

Delete Group

List Groups

Search Groups

Fields, Sort Order, and Paging

Searching Group Text Fields

Searching Group Time Fields

Search Groups Examples

Add User to Group

Delete User From Group

List Group Members by gid

List Group Members by Group name

Add a Policy to a Group

List Policies Bound to Group

Delete a Policy from Group

Keys/Values

The Key/Value Object

Create Key

Get Key Value

Update Key Value

Exists Key

Delete Key

Delete All Keys

List Keys

Search Keys and Values

Fields, Sort Order, and Paging

Searching Key/Value Text Fields

Searching Key/Value Time Fields

Search Key/Value Examples

Metrics

Health Status

Server Version

Unicode Support

JSON Output Encoding

List Group Members by `gid`

List Group Members by Group `name`