Skip to content

Creating and Managing Users

The main purpose of na-user is to manage user records.

The primary structure which defines a user is the user object. The API has REST calls which create, update, and manipulate the user object in typical fashion.

The User Object

The user object is a set of fields which holds the common information an online service may wish to track about its users.

The API presents the user object as a JSON entry with the following structure:

 {
    "banned": false,
    "birthdate": "1970-01-01",
    "country": "Luxembourg",
    "create_time": "2017-08-05T15:18:27Z",
    "disabled": false,
    "domain": "premium_users",
    "email": "bong6928@example.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://image-example.it/400x300",
    "postal_code": "85804",
    "profile_url": "https://social-example.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.example.com/"
  }

The user object schema is very flexible. When creating a user the only required field is the username which can be any UTF-8 string. All other fields are optional. Use as many or as few of the provided fields as needed.

Note that the timestamp fields create_time and update_time are system generated and can not be manipulated via the API.

Below is a description of each field and its type.

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, never returned in API calls
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

Working With the User Object

The na-user service has the following self explanatory API calls for manipulating the user object. See the The User Object section of the na-user API Reference for full syntax and important notes about using these calls:

API Call API Endpoint
Create User POST /users/create
Get User GET /users/get/{uid}
Update User POST /users/update/{uid}
Exists User GET /users/exists/{uid}
Delete User DELETE /users/delete/{uid}
List Users GET /users/list
Search Users POST /users/search

Many of the API calls have parameters which shape the returned responses.

For example the List Users API calls can limit the set of returned fields and their sort order. Similarly the Search Users API calls have many options for controlling which fields to search and in which order. Both also have options for controlling the paging of the resulting listings.

User Authentication

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.

However if password authentication is used then a user's authentication status can be queried with the /auth/login api call.

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