Users

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

User’s ID. Always starts with “usr_”. Example: usr_USkWvq7fl3LlYPKvqtxBq

state active,
inactive
active
realm_id realm_id Required ID of Realm this User belongs to.
user_type human,
api
Required
last_login_at time_t Time of last login, if any. Authentication by api_keys updates once per 24 hours.
reference string Optional Field to map to your app's own ID.
custom hash Optional Hash of custom attributes.
token string

Login session token (see Sessions).

request hash

Hash of request attributes to add to Event. See notes below.

human only:

username string Required Must be unique within realm.
email string Required
email_verification none,
requested,
verified
none See notes below.
first_name string Optional
last_name string Optional
name string Auto-generated Always populated on read, so useful for UI display.
password string Required

See below and Credentials.

password_confirmation string Optional

See below and Credentials.

api only:

username string Optional Must be unique within realm; auto-generated if empty.
email string Optional
name string Optional Auto-generated if empty.
api_key string Optional

See below and Credentials.

Passwords & API Keys

Passwords and API keys are now stored inside Credentials.

password and password_confirmation are both shortcuts to their respective values inside the User’s associated password-type Credential. Similarly, api_key is a shortcut to its matching value inside the User’s first associated api-key-type Credential.

User.api_key is deprecated and will be removed in a future version of the API. Use Credentials to manage API keys.

Usernames & Emails

Usernames and emails are always treated as case-insensitive and normalized to lower-case. This ensures that usernames like Johnny123 or Johnny@example.com aren’t treated as separate from johnny123 or johnny@example.com. You can safely save and even search by mixed-case though–we’ll handle everything properly.

Custom attributes

custom is hash/dictionary of custom attributes. Example:

{ "custom" : {
    "great_scott" : "value",
    "greatScott" : 2,
    "GreatScott" : true,
    "fantastic" : null
  }
}

Keys are case-sensitive, so the first three keys above are distinct keys. Keys must conform to /[a-z0-9_]/i.

Strings, numbers, booleans, and null are valid values. Values may also be an array of those same types.

To change existing values, update/resend the entire custom hash. To delete a key, simply update custom without that key.

Keys and values are not searchable (use reference if you need something searchable).

Email verification

none - No verification has taken place or is being attempted.
requested - Verification has been requested, but has not been successfully completed.
verified - Email has been verified.

On user creation, if set to requested, will trigger a user.email.verification_requested event in addition to user.created.

When updating email later, will not automatically clear verification or reverify (as verification is often only wanted once). Change to either none or requested if appropriate for your application.

Some social auth providers make the email verification state available. In this case, verified will be set automatically.

Reference

reference holds a single custom value and is always a string. It has the benefit of being searchable (see List Users).

It is most often used to hold a reference ID to an object inside your application. For example, it could hold some kind of account ID or instance ID.

Duplicate (non-unique) values are allowed.

Request attributes

request is hash/dictionary of request attributes. It is available on any API method that creates events.

All request attributes, and the request element itself, are optional. Valid attributes are:

  • client - Client software initiating action
  • ip - IP address of user performing action

Example:

{ "request" : {
    "client" : "MyApp for iOS/v1.0.0",
    "ip" : "10.0.0.1"
  }
}

Note that request goes outside the object hash:

//WRONG
{ "user" : {
    "username" : "jimmy",
    "request" : { "ip" : "10.0.0.1" }
  }
}
//CORRECT
{ "user" : { "username" : "jimmy" },
  "request" : { "ip" : "10.0.0.1" }
}

Permissions

MethodPermissions
List, Get read
All the rest write

List users

List all users in the current realm.

Parameters

ParamValueDefault
reference reference Filter by reference; must be an exact match
state state Filter by state
user_type all,
human,
api
all
after user_id ID of the last user you've seen
max_results integer 100 Range: 1-1000
sort id,
last_login,
name,
name_alt,
username
username

Human: name is “First Last”, name_alt is “Last, First”. For API, both natural.

direction asc,
desc
asc
expand custom

Include custom in the response

Request

Example
GET /v1/users?realm_id=rl_0v1zTHXhtNgmDaXaDYSAqx

Or, if the X-Authrocket-Realm: header is set:

GET /v1/users
$res = $client->users()->all();
AuthRocket::User.all realm_id: 'rl_0v1zTHXhtNgmDaXaDYSAqx'

Response

Example

Status: 200

{ "more_results" : false,
  "collection" : [
    { "id" : "usr_0v1zUpWdE4IiFc2w5ynShf",
      "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
      "username" : "dave",
      "state" : "active",
      "user_type" : "human",
      "reference" : null,
      "name" : "dave",
      "email" : "dave@example.com",
      "email_verification" : "none",
      "object" : "user",
      "last_login_at" : null,
      "created_at" : 1392447538.275,
      "first_name" : null,
      "last_name" : null
    }
  ]
}
var_dump($res->results);
  array(1) {
    [0]=>
    array(14) {
      ["id"]=> string(26) "usr_0v1zUpWdE4IiFc2w5ynShf"
      ["realm_id"]=> string(25) "rl_0v1zTHXhtNgmDaXaDYSAqx"
      ["username"]=> string(4) "dave"
      ["state"]=> string(6) "active"
      ["user_type"]=> string(5) "human"
      ["reference"]=> NULL
      ["name"]=> string(4) "dave"
      ["email"]=> string(16) "dave@example.com"
      ["email_verification"]=> string(4) "none"
      ["object"]=> string(4) "user"
      ["last_login_at"]=> NULL
      ["created_at"]=> float(1392447538.275)
      ["first_name"]=> NULL
      ["last_name"]=> NULL
    }
  }
[#<AuthRocket::User:0x3fde5fa18df8>
  id: "usr_0v1zUpWdE4IiFc2w5ynShf",
  attribs: {
    "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
    "username"=>"dave",
    "state"=>"active",
    "user_type"=>"human",
    "reference"=>nil,
    "name"=>"dave",
    "email"=>"dave@example.com",
    "email_verification"=>"none",
    "object"=>"user",
    "last_login_at"=>nil,
    "created_at"=>1392447538.275,
    "first_name"=>nil,
    "last_name"=>nil
  },
  metadata: {
    "more_results"=>false
  }
]

Get a user

Retrieve a specific user.

Parameters

ParamValueDefault
expand memberships Include membership and org details in the response

Request

Example
GET /v1/users/:user_id
GET /v1/users/:username
$res = $client->users()->find('usr_0v1zUpWdE4IiFc2w5ynShf');
$res = $client->users()->find('dave');
AuthRocket::User.find 'usr_0v1zUpWdE4IiFc2w5ynShf'
AuthRocket::User.find 'dave'

Response

Example

Status: 200

{ "id" : "usr_0v1zUpWdE4IiFc2w5ynShf",
  "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
  "username" : "dave",
  "state" : "active",
  "user_type" : "human",
  "reference" : null,
  "custom" : {},
  "name" : "dave",
  "email" : "dave@example.com",
  "email_verification" : "none",
  "object" : "user",
  "last_login_at" : null,
  "created_at" : 1392447538.275,
  "first_name" : null,
  "last_name" : null,
  "membership_count" : 0,
  "credentials" : [
    { "id" : "crd_0v9SwrveWnzli5xpTBWepd",
      "credential_type" : "password",
      "object" : "credential"
    }
  ]
}
var_dump($res->fields);
  array(17) {
    ["id"]=> string(26) "usr_0v1zUpWdE4IiFc2w5ynShf"
    ["realm_id"]=> string(25) "rl_0v1zTHXhtNgmDaXaDYSAqx"
    ["username"]=> string(4) "dave"
    ["state"]=> string(6) "active"
    ["user_type"]=> string(5) "human"
    ["reference"]=> NULL
    ["custom"]=> array(0) {}
    ["name"]=> string(4) "dave"
    ["email"]=> string(16) "dave@example.com"
    ["email_verification"]=> string(4) "none"
    ["object"]=> string(4) "user"
    ["last_login_at"]=> NULL
    ["created_at"]=> float(1392447538.275)
    ["first_name"]=> NULL
    ["last_name"]=> NULL
    ["membership_count"]=> int(0)
    ["credentials"]=> array(1) {
      [0]=>
      array(3) {
        ["id"]=> string(26) "crd_0v9SwrveWnzli5xpTBWepd"
        ["credential_type"]=> string(8) "password"
        ["object"]=> string(10) "credential"
      }
    }
  }
#<AuthRocket::User:0x3fde5fa18df8>
  id: "usr_0v1zUpWdE4IiFc2w5ynShf",
  attribs: {
    "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
    "username"=>"dave",
    "state"=>"active",
    "user_type"=>"human",
    "reference"=>nil,
    "custom"=>{},
    "name"=>"dave",
    "email"=>"dave@example.com",
    "email_verification"=>"none",
    "object"=>"user",
    "last_login_at"=>nil,
    "created_at"=>1392447538.275,
    "first_name"=>nil,
    "last_name"=>nil,
    "membership_count"=>0,
    "credentials"=>[
      #<AuthRocket::Credential:0x3fc21aaf2a00>
        id: "crd_0v9SwrveWnzli5xpTBWepd",
        attribs: {
          "credential_type"=>"password",
          "object"=>"credential"
        }
    ]
  }

Create a user

Create a new user. Users may be created normally, with a hash full of data, or from a Signup Token. Only human users may be created with a Signup Token.

Parameters

ParamValueDefault
org_ids org_ids One, or an array of, org_ids used to auto-build memberships for the new user.
org object

A valid org json object (see Create an Org) to create alongside this user. Will auto-build a membership between the two.

permissions string

One, or an array of, permissions to use for all memberships created via org_ids or org. If provided without org or org_ids, auto-builds one membership with no org.

Extra parameters are all optional. org should be a standard hash when using the Ruby bindings.

Request

Example
POST /v1/users
{ "user" : {
    "username" : "dave",
    "user_type" : "human"
  }
}


POST /v1/users
{ "user" : {
    "token" : "utk_abcdefg"
  }
}
$res = $client->users()->create([
  "username" => "dave",
  "user_type" => "human"
]);


$res = $client->users()->create([
  "token" => "utk_abcdefg"
]);
user = AuthRocket::User.create(
  username: 'dave',
  user_type: 'human'
)


user = AuthRocket::User.create(
  token: 'utk_abcdefg'
)

Response

Example

Status: 201, with same body as Get a User.

On success, returns same object as Get a User.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(23) "Username can't be blank"
  }

On success, returns same object as Get a User.

On failure, returns an object without an id, but with errors:

# => #<AuthRocket::User:0x3fde5fa18df8> id: nil, ...
user.errors?
# => true
user.valid?
# => false
user.errors
# => ["Username can't be blank"]

Events

Triggers a user.created event. May trigger a user.email.verification_requested or user.email.verified event. If org is provided, triggers org.created. If org and/or org_ids provided, triggers one or more membership.created events.

Update a user

Update a user’s attributes. Only provided attributes are changed.

Request

Example
PUT /v1/users/:user_id
PUT /v1/users/:username
{ "user" : {
    "first_name" : "Dave",
    "last_name" : "Smith"
  }
}
$res = $client->users()->update('usr_0v1zUpWdE4IiFc2w5ynShf', [
  "first_name" => "Dave",
  "last_name" => "Smith"
]);
user=AuthRocket::User.find 'usr_0v1zUpWdE4IiFc2w5ynShf'
user.save first_name: 'Dave', last_name: 'Smith'

Response

Example

Status: 200, with same body as Get a User.

On success, returns same object as Get a User.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(23) "Username can't be blank"
  }

On success, returns same object as Get a User.

On failure, returns false:

# => false
user.errors
# => ["Username can't be blank"]

Events

Triggers a user.updated event. May trigger a user.email.verification_requested or user.email.verified event.

Update password

Confirms the existing password and then updates the password. Administrative password resets should use Update a User. Self-service password resets should use Generate a Password Token and Reset Password with a Token.

Parameters

ParamValueDefault
current_password string Required
password string Required
password_confirmation string Required

Request

Example
PUT /v1/users/:user_id/update_password
PUT /v1/users/:username/update_password
{ "user" : {
    "current_password" : "old_secret",
    "password" : "new_secret",
    "password_confirmation" : "new_secret"
  }
}
$res = $client->users()->updatePassword('usr_0v1zUpWdE4IiFc2w5ynShf', [
  "current_password" => "old_secret",
  "password" => "new_secret",
  "password_confirmation" => "new_secret"
]);
user=AuthRocket::User.find 'usr_0v1zUpWdE4IiFc2w5ynShf'
user.update_password(
  current_password: 'old_secret',
  password: 'new_secret',
  password_confirmation: 'new_secret'
)

Response

Example

Status: 204 on success.
Status: 422 on error validating existing or new password.
Status: 429 if blocked for too many password attempts.

On success, returns same object as Get a User.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(36) "Password confirmation does not match"
  }

On success, returns same object as Get a User.

On failure, returns false:

# => false
user.errors
# => ["Password confirmation does not match"]

Events

Triggers a user.updated event.

Delete a user

Deletes a user.

Request

Example
DELETE /v1/users/:user_id
DELETE /v1/users/:username
$res = $client->users()->delete('usr_0v1zUpWdE4IiFc2w5ynShf');
user=AuthRocket::User.find 'usr_0v1zUpWdE4IiFc2w5ynShf'
user.delete

Response

Example

Status: 204

On success, returns an object with no errors.

On failure, returns an object with errors.

$res->hasErrors();
// => true or false

On success, returns original object.

On failure, returns false.

Events

Triggers a user.deleted event and zero or more membership.deleted events.

Authenticate using a password

Checks authentication data for a human user. The user must be active and password must match.

When the user is configured for multi-factor authentication, returns a token beginning with kli_ instead of a login token.

Parameters

ParamValueDefault
password string Required. User's password.
expand memberships Include membership and org details in the response

Request

Example
POST /v1/users/:user_id/authenticate
POST /v1/users/:username/authenticate
{ "password" : "secret",
  "request" : {
    "ip" : "127.0.0.1",
    "client" : "user's User-Agent header"
  }
}
$res = $client->users()->authenticate('username_or_id', 'secret');
user=AuthRocket::User.authenticate 'username_or_id', 'secret'

Response

Example

Status: 200 with same body as Get a User, plus:

{ ... ,
  "token" : "4JagCZeSCVH...ae2kd9ZOaWo"
}

Status: 401 if user found, but password doesn’t match.
Status: 404 if user not found.
Status: 429 if blocked for too many password attempts.

On success, returns same object as Get a User plus a token attribute.

On failure, throws an exception.

On success, returns same object as Get a User plus a token attribute.

On failure, raises an exception.

Events

Triggers a user.login.succeeded, user.login.initiated (MFA), or user.login.failed event.

Complete an MFA authentication

Finishes an authentication that requires a multi-factor authentication (MFA) verification code.

Returns the same token that authenticate would have had MFA not been enabled.

Parameters

ParamValueDefault
token string

Required. The token return by /authenticate above. Starts with kli_.

code string Required. 6-digit MFA verification code.
expand memberships Include membership and org details in the response.

Request

Example
POST /v1/users/:user_id/authenticate_code
POST /v1/users/:username/authenticate_code
{ "user" : {
    "token" : "kli_76FT6i10aYVh27xXVToHo0",
    "code" : "123456"
  },
  "request" : {
    "ip" : "127.0.0.1",
    "client" : "user's User-Agent header"
  }
}
$res = $client->users()->authenticateCode('username_or_id', [
  "token" => "kli_abcdefghij",
  "code" => "123456"
]);
user=AuthRocket::User.authenticate_code 'username_or_id', 'kli_abcdefghij', '123456'

Response

Example

Status: 200 with same body as Get a User, plus:

{ ... ,
  "token" : "4JagCZeSCVH...ae2kd9ZOaWo"
}

Status: 401 if token found, but code doesn’t match. May try again.
Status: 404 if token not found, expired, or already used. Don’t try again.
Status: 429 if blocked for too many attempts.

On success, returns same object as Get a User plus a token attribute.

On failure, throws an exception.

On success, returns same object as Get a User plus a token attribute.

On failure, raises an exception.

Events

Triggers either a user.login.succeeded or a user.login.failed event.

Authenticate using an API key

Checks authentication data for an api user. The user must be active and api_key must match.

Records only the first successful authentication event each day. Does not trigger AppHooks when events are not recorded.

For session-based usage (web or APIs) with a single login at the beginning of a session, use Authenticate using a password at the time of initial login, store the user ID or entire user record in the session, and use Get a user when needed.

For non-session-based APIs, use this method instead so as to reduce unnecessary generation and storage of events.

Parameters

ParamValueDefault
api_key string Required. User's API key.
expand memberships Include membership and org details in the response

Request

Example
POST /v1/users/authenticate_key
{ "api_key" : "secret_key",
  "request" : {
    "ip" : "127.0.0.1"
  }
}
$res = $client->users()->authenticateKey('secret_key');
user=AuthRocket::User.authenticate_key 'secret_key'

Response

Example

Status: 200 with same body as Get a User.
Status: 404 if user not found.

On success, returns same object as Get a User.

On failure, throws an exception.

On success, returns same object as Get a User.

On failure, raises an exception.

Events

Triggers a user.login.succeeded event on the first authentication each day.

Generate an email verification token

Generates a token for verifying an email address.

Will email the token to the user if a matching AppHook exists and is enabled.

If called when a token is already pending, will generate another token and event. Useful for resending verification emails. If called when email is in verified state, will unverify it.

Request

Example
POST /v1/users/:user_id/request_email_verification
POST /v1/users/:username/request_email_verification
{ "request" : {
    "ip" : "127.0.0.1"
  }
}
$res = $client->users()->requestEmailVerification('username_or_id', [
  "request" => ["ip" => "127.0.0.1" ]
]);
user=AuthRocket::User.find 'username_or_id'
user.request_email_verification request: {ip: '127.0.0.1'}

Response

Example

Status: 200

{ "id" : "usr_0v1zUpWdE4IiFc2w5ynShf",
  "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
  "username" : "dave",
  "email" : "dave@example.com",
  "object" : "user",
  "token" : "kv_4JagCZeSCVHae2kd9ZOaWo"
}

Status: 429 if blocked for too many token generation requests.

On success, returns partial user object with a token attribute.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(5) "Error"
  }

On success, returns user object with a token attribute.

On failure, returns false:

# => false
user.errors
# => ["Error"]

Events

Triggers a user.email.verification_requested event.

Verify an email

Verifies an email address using a previously generated token. Tokens are valid for 7 days from creation. If a user successfully verifies an email, all prior tokens are invalidated. Tokens may be used once.

Parameters

ParamValueDefault
token string Required. Email verification token.

Request

Example
POST /v1/users/:user_id/verify_email
POST /v1/users/:username/verify_email
{ "request" : {
    "ip" : "127.0.0.1"
  },
  "user" : {
    "token" : "kv_5Jf0IRSiChW7M2HVqxXujL"
  }
}
$res = $client->users()->verifyEmail('username_or_id', 'kv_5Jf0IRSiChW7M2HVqxXujL', [
  "request" => ["ip" => "127.0.0.1" ]
]);
user=AuthRocket::User.find username_or_id
user.verify_email token: 'kv_5Jf0IRSiChW7M2HVqxXujL', request: {ip: '127.0.0.1'}

Response

Example

Status: 200 on success, with same body as Get a User.

On success, returns same object as Get a User.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(31) "Verification token already used"
  }

On success, returns same object as Get a User.

On failure, returns false:

# => false
user.errors
# => ["Verification token already used"]

Events

Triggers a user.email.verified event. Does not trigger user.updated.

Generate a password token

Generates a password token that can be used to reset a forgotten password. Only valid for active, human users. Generating a new token invalidates any prior tokens.

Will send the token to the user by email if a matching AppHook exists and is enabled (which is true by default).

Request

Example
POST /v1/users/:user_id/generate_password_token
POST /v1/users/:username/generate_password_token
{ "request" : {
    "ip" : "127.0.0.1"
  }
}
$res = $client->users()->generatePasswordToken('username_or_id', [
  "request" => ["ip" => "127.0.0.1" ]
]);
user=AuthRocket::User.generate_password_token 'username_or_id', request: {ip: '127.0.0.1'}

Response

Example

Status: 200

{ "id" : "usr_0v1zUpWdE4IiFc2w5ynShf",
  "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
  "username" : "dave",
  "object" : "user",
  "password_reset_token" : "kpw_4JagCZeSCVHae2kd9ZOaWo"
}

Status: 422 if unable to generate the token.
Status: 429 if blocked for too many token generation requests.

On success, returns partial user object with a password_reset_token attribute.

On failure, throws an exception.

On success, returns user object with a password_reset_token attribute.

On failure, raises an exception.

Events

Triggers a user.password_token.created event.

Reset password with a token

Validates a password token and resets a user’s password. Tokens are valid for 3 days from creation. If a user successfully logs in with the existing password, the token is invalidated. Tokens may be used once.

Parameters

ParamValueDefault
password string Required
password_confirmation string Optional
token string Required. Password reset token.

Request

Example
POST /v1/users/:user_id/reset_password_with_token
POST /v1/users/:username/reset_password_with_token
{ "request" : {
    "ip" : "127.0.0.1"
  },
  "user" : {
    "password" : "secret",
    "password_confirmation" : "secret",
    "token" : "kpw_5Jf0IRSiChW7M2HVqxXujL"
  }
}
$res = $client->users()->resetPasswordWithToken('username_or_id', [
  "token" => "kpw_5Jf0IRSiChW7M2HVqxXujL",
  "password" => "secret",
  "password_confirmation" => "secret",
  "request" => ["ip" => "127.0.0.1" ]
]);
user=AuthRocket::User.reset_password_with_token(username_or_id, token,
  'secret', 'secret', request: {ip: '127.0.0.1'})

Response

Example

Status: 200 on success, with same body as Get a User.
Status: 404 if user or token not found.
Status: 422 for validation error on new password.

On success, returns same object as Get a User.

On failure, throws an exception.

On success, returns same object as Get a User.

On failure, raises an exception.

Events

Triggers either a user.password_token.consumed (success) or user.password_token.failed (failure) event. Does not trigger user.updated.

Questions? Find a Typo? Get in touch.