Users

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

User’s ID. Starts with “usr_”. Example: usr_0v1zUpWdE4IiFc2w5ynShf
state active, inactive active
realm_id realm_id Required ID of Realm this User belongs to.
created_at time_t
last_login_at time_t Time of last login.
email string Required Must be unique within the realm.
email_pending string Email change awaiting verification.
email_verification none, requested, verified none See notes below.
first_name string Optional
last_name string Optional
locale string Optional User's preferred locale.
name string Auto-generated Always populated on read, so useful for UI display.
username string Optional
password string Required

See below and Credentials.
password_confirmation string Optional

See below and Credentials.
reference string Optional Field to map to your app's own ID.
custom hash Optional Hash of custom attributes.
request hash

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

Emails

Emails are normalized to lower-case and must be unique within the realm. You can safely save and even filter by mixed-case though—we’ll handle everything properly.

Emails may also be used as an alternate key instead of the ID.

Email pending

Email changes can be effective immediately, or conditional upon successful verification.

To change an email immediately, update email. To request verification of the new email after a change, also set email_verification = requested.

To change an email conditionally, update email_pending. This will trigger a user.email.updating event, which will send a verification email by default. Upon successful verification, the newly verified email will be automatically moved to email, email_pending will be cleared, and email_verification set to verified.

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.verifying 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.

Passwords

Passwords are stored inside Credentials.

password and password_confirmation are both shortcuts to their respective values inside the User’s associated password-type Credential.

Usernames

Usernames are case-preserving, but otherwise treated case-insensitively. This ensures that a username like Johnny123 isn’t treated as separate from johnny123.

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).

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:

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" }
}

Required permissions

MethodPermissions
List, Get read
All the rest write

List users

List all users in the current realm.

Parameters

ParamValueDefault
email email Filter by email; normalized for case, but otherwise must be an exact match
reference reference Filter by reference; must be an exact match
username string Filter by username; normalized for case, but otherwise must be an exact match
state state Filter by state
after user_id ID of the last user you've seen
max_results integer 100 Range: 1-1000
sort id, email, last_login, name, name_alt, username email

name is “First Last”, name_alt is “Last, First”.
direction asc, desc asc
expand custom

Include custom in the response

Request

Example
GET /v2/users

Or, if a default realm is not set:

GET /v2/users?realm_id=rl_sample123456

var resp = await authrocket.users.all()
$res = $authrocket->users->all();
AuthRocket::User.all realm_id: "rl_sample123456"

Response

Example

Status: 200

{
  "collection": [
    {
      "created_at": 1735689600.0,
      "email": "davy@example.com",
      "email_pending": null,
      "email_verification": "none",
      "first_name": "Davy",
      "id": "usr_sample123456",
      "last_login_at": null,
      "last_name": "Crockett",
      "locale": null,
      "name": "Davy Crockett",
      "object": "user",
      "realm_id": "rl_sample123456",
      "reference": null,
      "state": "active",
      "username": "davy"
    }
  ],
  "more_results": false
}

// console.log(resp.results)
[
  {
    created_at: 1735689600.0,
    email: "davy@example.com",
    email_pending: null,
    email_verification: "none",
    first_name: "Davy",
    id: "usr_sample123456",
    last_login_at: null,
    last_name: "Crockett",
    locale: null,
    name: "Davy Crockett",
    object: "user",
    realm_id: "rl_sample123456",
    reference: null,
    state: "active",
    username: "davy"
  }
]
// var_dump($res->results);
array(1) {
  [0]=> 
    array(15) {
      ["created_at"]=> float(1735689600.0)
      ["email"]=> string(16) "davy@example.com"
      ["email_pending"]=> NULL
      ["email_verification"]=> string(4) "none"
      ["first_name"]=> string(4) "Davy"
      ["id"]=> string(16) "usr_sample123456"
      ["last_login_at"]=> NULL
      ["last_name"]=> string(8) "Crockett"
      ["locale"]=> NULL
      ["name"]=> string(13) "Davy Crockett"
      ["object"]=> string(4) "user"
      ["realm_id"]=> string(15) "rl_sample123456"
      ["reference"]=> NULL
      ["state"]=> string(6) "active"
      ["username"]=> string(4) "davy"
    }
}
[AuthRocket::User(
  created_at: 2025-01-01 00:00:00 UTC,
  email: "davy@example.com",
  email_pending: nil,
  email_verification: "none",
  first_name: "Davy",
  id: "usr_sample123456",
  last_login_at: nil,
  last_name: "Crockett",
  locale: nil,
  name: "Davy Crockett",
  realm_id: "rl_sample123456",
  reference: nil,
  state: "active",
  username: "davy"
 )
]

Get a user

Retrieve a specific user.

To minimize API response time and keep your app snappy, please remember to only expand the minimum data necessary.

Parameters

ParamValueDefault
expand memberships Include membership+org details in the response.

Request

Example
GET /v2/users/usr_sample123456  # by user id
GET /v2/users/davy@example.com  # by email

var resp = await authrocket.users.find("usr_sample123456")
var resp = await authrocket.users.find("davy@example.com")
$res = $authrocket->users->find("usr_sample123456");
$res = $authrocket->users->find("davy@example.com");
user = AuthRocket::User.find "usr_sample123456"
user = AuthRocket::User.find "davy@example.com"

Response

Example

Status: 200

{
  "created_at": 1735689600.0,
  "credentials": [
    {
      "credential_type": "password",
      "id": "crd_sample123456",
      "object": "credential"
    }
  ],
  "custom": {},
  "email": "davy@example.com",
  "email_pending": null,
  "email_verification": "none",
  "first_name": "Davy",
  "id": "usr_sample123456",
  "last_login_at": null,
  "last_name": "Crockett",
  "locale": null,
  "membership_count": 0,
  "name": "Davy Crockett",
  "object": "user",
  "realm_id": "rl_sample123456",
  "reference": null,
  "state": "active",
  "username": "davy"
}

// console.log(resp.results)
{
  created_at: 1735689600.0,
  credentials: [
    {
      credential_type: "password",
      id: "crd_sample123456",
      object: "credential"
    }
  ],
  custom: {},
  email: "davy@example.com",
  email_pending: null,
  email_verification: "none",
  first_name: "Davy",
  id: "usr_sample123456",
  last_login_at: null,
  last_name: "Crockett",
  locale: null,
  membership_count: 0,
  name: "Davy Crockett",
  object: "user",
  realm_id: "rl_sample123456",
  reference: null,
  state: "active",
  username: "davy"
}
// var_dump($res->fields);
array(18) {
  ["created_at"]=> float(1735689600.0)
  ["credentials"]=> 
    array(1) {
      [0]=> 
        array(3) {
          ["credential_type"]=> string(8) "password"
          ["id"]=> string(16) "crd_sample123456"
          ["object"]=> string(10) "credential"
        }
    }
  ["custom"]=> array(0) {}
  ["email"]=> string(16) "davy@example.com"
  ["email_pending"]=> NULL
  ["email_verification"]=> string(4) "none"
  ["first_name"]=> string(4) "Davy"
  ["id"]=> string(16) "usr_sample123456"
  ["last_login_at"]=> NULL
  ["last_name"]=> string(8) "Crockett"
  ["locale"]=> NULL
  ["membership_count"]=> int(0)
  ["name"]=> string(13) "Davy Crockett"
  ["object"]=> string(4) "user"
  ["realm_id"]=> string(15) "rl_sample123456"
  ["reference"]=> NULL
  ["state"]=> string(6) "active"
  ["username"]=> string(4) "davy"
}
AuthRocket::User(
 created_at: 2025-01-01 00:00:00 UTC,
 credentials: 
  [AuthRocket::Credential(credential_type: "password", id: "crd_sample123456"
   )],
 custom: {},
 email: "davy@example.com",
 email_pending: nil,
 email_verification: "none",
 first_name: "Davy",
 id: "usr_sample123456",
 last_login_at: nil,
 last_name: "Crockett",
 locale: nil,
 membership_count: 0,
 name: "Davy Crockett",
 realm_id: "rl_sample123456",
 reference: nil,
 state: "active",
 username: "davy"
)

Create a user

Create a new user.

Parameters

ParamValueDefault
credentials objects

An array of valid credential json objects (see Create a Credential) to create for this user.
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 strings

One, or an array of, permissions to use for all memberships created via org_ids or org.

Extra parameters are all optional. org should be a simple hash/dict/json object.

Either credentials or password may be sent. Behavior is undefined if both are used.

Request

Example
POST /v2/users

{
  "user": {
    "email": "dcrockett@example.com",
    "password": "secret"
  }
}

var resp = await authrocket.users.create({
  email: "dcrockett@example.com",
  password: "secret"
})
$res = $authrocket->users->create([
  "email" => "dcrockett@example.com",
  "password" => "secret"
]);
user = AuthRocket::User.create(
  email: "dcrockett@example.com",
  password: "secret"
)

Response

Example

On success, status 201 with the new User.

{
  "created_at": 1735689600.0,
  "credentials": [
    {
      "credential_type": "password",
      "id": "crd_sample123456",
      "object": "credential"
    }
  ],
  "custom": {},
  "email": "dcrockett@example.com",
  "email_pending": null,
  "email_verification": "none",
  "first_name": null,
  "id": "usr_sample123456",
  "last_login_at": null,
  "last_name": null,
  "locale": null,
  "membership_count": 0,
  "memberships": [],
  "name": "dcrockett@example.com",
  "new_record": true,
  "object": "user",
  "realm_id": "rl_sample123456",
  "reference": null,
  "state": "active",
  "username": null
}

On failure, status 422 with a standard error response.

On success, returns an object with the new User.

// console.log(resp.results)
{
  created_at: 1735689600.0,
  credentials: [
    {
      credential_type: "password",
      id: "crd_sample123456",
      object: "credential"
    }
  ],
  custom: {},
  email: "dcrockett@example.com",
  email_pending: null,
  email_verification: "none",
  first_name: null,
  id: "usr_sample123456",
  last_login_at: null,
  last_name: null,
  locale: null,
  membership_count: 0,
  memberships: [],
  name: "dcrockett@example.com",
  new_record: true,
  object: "user",
  realm_id: "rl_sample123456",
  reference: null,
  state: "active",
  username: null
}

On failure, returns an object with a standard error response.

On success, returns an object with the new User.

// var_dump($res->fields);
array(20) {
  ["created_at"]=> float(1735689600.0)
  ["credentials"]=> 
    array(1) {
      [0]=> 
        array(3) {
          ["credential_type"]=> string(8) "password"
          ["id"]=> string(16) "crd_sample123456"
          ["object"]=> string(10) "credential"
        }
    }
  ["custom"]=> array(0) {}
  ["email"]=> string(21) "dcrockett@example.com"
  ["email_pending"]=> NULL
  ["email_verification"]=> string(4) "none"
  ["first_name"]=> NULL
  ["id"]=> string(16) "usr_sample123456"
  ["last_login_at"]=> NULL
  ["last_name"]=> NULL
  ["locale"]=> NULL
  ["membership_count"]=> int(0)
  ["memberships"]=> array(0) {}
  ["name"]=> string(21) "dcrockett@example.com"
  ["new_record"]=> bool(true)
  ["object"]=> string(4) "user"
  ["realm_id"]=> string(15) "rl_sample123456"
  ["reference"]=> NULL
  ["state"]=> string(6) "active"
  ["username"]=> NULL
}

On failure, returns an object with a standard error response.

On success, returns an object with the new User.

AuthRocket::User(
 created_at: 2025-01-01 00:00:00 UTC,
 credentials: 
  [AuthRocket::Credential(credential_type: "password", id: "crd_sample123456"
   )],
 custom: {},
 email: "dcrockett@example.com",
 email_pending: nil,
 email_verification: "none",
 first_name: nil,
 id: "usr_sample123456",
 last_login_at: nil,
 last_name: nil,
 locale: nil,
 membership_count: 0,
 memberships: [],
 name: "dcrockett@example.com",
 new_record: true,
 realm_id: "rl_sample123456",
 reference: nil,
 state: "active",
 username: nil
)

On failure, returns an object with a standard error response.

Events

Triggers a user.created event. May trigger user.email.verifying or user.email.verified. When org is provided, triggers org.created. If memberships are built, triggers corresponding membership.created events.

Update a user

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

Request

Example
PUT /v2/users/usr_sample1234556
PUT /v2/users/davy@example.com

{
  "user": {
    "first_name": "Davy",
    "last_name": "Crockett"
  }
}

var resp = await authrocket.users.update("usr_sample123456", {
  first_name: "Davy",
  last_name: "Crockett"
})
$res = $authrocket->users->update("usr_sample123456", [
  "first_name" => "Davy",
  "last_name" => "Crockett"
]);
user = AuthRocket::User.find "usr_sample123456"
user.update first_name: "Davy", last_name: "Crockett"

Response

Example

On success, status 200 with the updated User.

{
  "created_at": 1735689600.0,
  "credentials": [
    {
      "credential_type": "password",
      "id": "crd_sample123456",
      "object": "credential"
    }
  ],
  "custom": {},
  "email": "davy@example.com",
  "email_pending": null,
  "email_verification": "none",
  "first_name": "Davy",
  "id": "usr_sample123456",
  "last_login_at": null,
  "last_name": "Crockett",
  "locale": null,
  "membership_count": 0,
  "name": "Davy Crockett",
  "object": "user",
  "realm_id": "rl_sample123456",
  "reference": null,
  "state": "active",
  "username": "davy"
}

On failure, status 422 with a standard error response.

On success, returns an object with the updated User.

// console.log(resp.results)
{
  created_at: 1735689600.0,
  credentials: [
    {
      credential_type: "password",
      id: "crd_sample123456",
      object: "credential"
    }
  ],
  custom: {},
  email: "davy@example.com",
  email_pending: null,
  email_verification: "none",
  first_name: "Davy",
  id: "usr_sample123456",
  last_login_at: null,
  last_name: "Crockett",
  locale: null,
  membership_count: 0,
  name: "Davy Crockett",
  object: "user",
  realm_id: "rl_sample123456",
  reference: null,
  state: "active",
  username: "davy"
}

On failure, returns an object with a standard error response.

On success, returns an object with the updated User.

// var_dump($res->fields);
array(18) {
  ["created_at"]=> float(1735689600.0)
  ["credentials"]=> 
    array(1) {
      [0]=> 
        array(3) {
          ["credential_type"]=> string(8) "password"
          ["id"]=> string(16) "crd_sample123456"
          ["object"]=> string(10) "credential"
        }
    }
  ["custom"]=> array(0) {}
  ["email"]=> string(16) "davy@example.com"
  ["email_pending"]=> NULL
  ["email_verification"]=> string(4) "none"
  ["first_name"]=> string(4) "Davy"
  ["id"]=> string(16) "usr_sample123456"
  ["last_login_at"]=> NULL
  ["last_name"]=> string(8) "Crockett"
  ["locale"]=> NULL
  ["membership_count"]=> int(0)
  ["name"]=> string(13) "Davy Crockett"
  ["object"]=> string(4) "user"
  ["realm_id"]=> string(15) "rl_sample123456"
  ["reference"]=> NULL
  ["state"]=> string(6) "active"
  ["username"]=> string(4) "davy"
}

On failure, returns an object with a standard error response.

On success, returns an object with the updated User.

AuthRocket::User(
 created_at: 2025-01-01 00:00:00 UTC,
 credentials: 
  [AuthRocket::Credential(credential_type: "password", id: "crd_sample123456"
   )],
 custom: {},
 email: "davy@example.com",
 email_pending: nil,
 email_verification: "none",
 first_name: "Davy",
 id: "usr_sample123456",
 last_login_at: nil,
 last_name: "Crockett",
 locale: nil,
 membership_count: 0,
 name: "Davy Crockett",
 realm_id: "rl_sample123456",
 reference: nil,
 state: "active",
 username: "davy"
)

On failure, returns an object with a standard error response.

Events

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

Update password

Confirms the existing password and then updates the password. Intended for use on a profile or password update page.

Administrative password resets should use Update a Credential or Update Profile depending on what events should be generated.

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 /v2/users/usr_sample1234556/update_password
PUT /v2/users/davy@example.com/update_password

{
  "user": {
    "current_password": "old_secret",
    "password": "new_secret",
    "password_confirmation": "new_secret"
  }
}

var resp = await authrocket.users.updatePassword("usr_sample123456", {
  current_password: "old_secret",
  password: "new_secret",
  password_confirmation: "new_secret"
})
$res = $authrocket->users->updatePassword("usr_sample123456", [
  "current_password" => "old_secret",
  "password" => "new_secret",
  "password_confirmation" => "new_secret"
]);
user = AuthRocket::User.find "usr_sample123456"
user.update_password(
  current_password: "old_secret",
  password: "new_secret",
  password_confirmation: "new_secret"
)

Response

Example

On success, status 204 with an empty response.
On failure, status 422 with a standard error response.

On success, returns an object with no errors.
On failure, returns an object with a standard error response.

On success, returns an object with no errors.
On failure, returns an object with a standard error response.

On success, returns the original object with no errors.
On failure, returns false with errors added to original object.

Events

Triggers user.updated and user.password.updated events.

Update profile

Updates selected fields as part of the user profile and generates extra events intended for user notification.

Password changes here do not require confirmation of the previous password. For that, see Update password. This API may be used to set a password for a user who does not have one (perhaps because they originally signed up using social login).

Allowed attributes: email, email_pending, email_verification, first_name, last_name, locale, password, password_confirmation, username.

In contrast to Update a user, email_verification is ignored unless email is actually changed. As such, it is safe to submit email whether or not changed, and to submit email_verification = requested every time, assuming you wish to re-verify emails upon every change.

Request

Example
PUT /v2/users/usr_sample1234556/profile
PUT /v2/users/davy@example.com/profile

{
  "user": {
    "email": "dcrockett@example.com"
  }
}

var resp = await authrocket.users.updateProfile("usr_sample123456", {
  email: "dcrockett@example.com"
})
$res = $authrocket->users->updateProfile("usr_sample123456", [
  "email" => "dcrockett@example.com"
]);
user = AuthRocket::User.find "usr_sample123456"
user.update_profile(
  email: "dcrockett@example.com"
)

Response

Example

On success, status 200 with the updated User.

{
  "created_at": 1735689600.0,
  "credentials": [
    {
      "credential_type": "password",
      "id": "crd_sample123456",
      "object": "credential"
    }
  ],
  "custom": {},
  "email": "dcrockett@example.com",
  "email_pending": null,
  "email_verification": "none",
  "first_name": "Davy",
  "id": "usr_sample123456",
  "last_login_at": null,
  "last_name": "Crockett",
  "locale": null,
  "membership_count": 0,
  "name": "Davy Crockett",
  "object": "user",
  "realm_id": "rl_sample123456",
  "reference": null,
  "state": "active",
  "username": "davy"
}

On failure, status 422 with a standard error response.

On success, returns an object with the updated User.

// console.log(resp.results)
{
  created_at: 1735689600.0,
  credentials: [
    {
      credential_type: "password",
      id: "crd_sample123456",
      object: "credential"
    }
  ],
  custom: {},
  email: "dcrockett@example.com",
  email_pending: null,
  email_verification: "none",
  first_name: "Davy",
  id: "usr_sample123456",
  last_login_at: null,
  last_name: "Crockett",
  locale: null,
  membership_count: 0,
  name: "Davy Crockett",
  object: "user",
  realm_id: "rl_sample123456",
  reference: null,
  state: "active",
  username: "davy"
}

On failure, returns an object with a standard error response.

On success, returns an object with the updated User.

// var_dump($res->fields);
array(18) {
  ["created_at"]=> float(1735689600.0)
  ["credentials"]=> 
    array(1) {
      [0]=> 
        array(3) {
          ["credential_type"]=> string(8) "password"
          ["id"]=> string(16) "crd_sample123456"
          ["object"]=> string(10) "credential"
        }
    }
  ["custom"]=> array(0) {}
  ["email"]=> string(21) "dcrockett@example.com"
  ["email_pending"]=> NULL
  ["email_verification"]=> string(4) "none"
  ["first_name"]=> string(4) "Davy"
  ["id"]=> string(16) "usr_sample123456"
  ["last_login_at"]=> NULL
  ["last_name"]=> string(8) "Crockett"
  ["locale"]=> NULL
  ["membership_count"]=> int(0)
  ["name"]=> string(13) "Davy Crockett"
  ["object"]=> string(4) "user"
  ["realm_id"]=> string(15) "rl_sample123456"
  ["reference"]=> NULL
  ["state"]=> string(6) "active"
  ["username"]=> string(4) "davy"
}

On failure, returns an object with a standard error response.

On success, returns an object with the updated User.

AuthRocket::User(
 created_at: 2025-01-01 00:00:00 UTC,
 credentials: 
  [AuthRocket::Credential(credential_type: "password", id: "crd_sample123456"
   )],
 custom: {},
 email: "dcrockett@example.com",
 email_pending: nil,
 email_verification: "none",
 first_name: "Davy",
 id: "usr_sample123456",
 last_login_at: nil,
 last_name: "Crockett",
 locale: nil,
 membership_count: 0,
 name: "Davy Crockett",
 realm_id: "rl_sample123456",
 reference: nil,
 state: "active",
 username: "davy"
)

On failure, returns false with errors added to original object.

Events

Triggers a user.updated event along with user.profile.updated and/or user.password.updated events.

Delete a user

Deletes a user.

Request

Example
DELETE /v2/users/usr_sample1234556
DELETE /v2/users/davy@example.com

var resp = await authrocket.users.delete("usr_sample123456")
$res = $authrocket->users->delete("usr_sample123456");
user = AuthRocket::User.find "usr_sample123456"
user.delete

Response

Example

On success, status 204 with an empty response.
On failure, status 422 with a standard error response.

On success, returns an object with no errors.
On failure, returns an object with a standard error response.

On success, returns an object with no errors.
On failure, returns an object with a standard error response.

On success, returns the original object with no errors.
On failure, returns false with errors added to original object.

Events

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

Authenticate using a password

Authenticates a user using a password. The user must be active and have a password.

When the user is configured for multi-factor authentication, returns an MFA token beginning with tmf:. Otherwise, returns a session with session token.

Parameters

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

Request

Example
POST /v2/users/usr_sample1234556/authenticate
POST /v2/users/davy@example.com/authenticate

{
  "request": {
    "client": "user's User-Agent header",
    "ip": "10.0.0.1"
  },
  "user": {
    "password": "secret"
  }
}

var resp = await authrocket.users.authenticate("davy@example.com", {
  password: "secret"
})
$res = $authrocket->users->authenticate("davy@example.com", [
  "password" => "secret"
]);
session_or_token = AuthRocket::User.authenticate "davy@example.com",
  password: "secret"

Response

Example

On success without MFA, status 201 with a new Session.

{
  "client_app_id": null,
  "created_at": 1735689600.0,
  "expires_at": 1735776000,
  "id": "kss_sample123456",
  "object": "session",
  "request": {
    "client": "user's User-Agent header",
    "ip": "10.0.0.1"
  },
  "token": "eyJ...",
  "user": {
    "created_at": 1735689600.0,
    "credentials": [
      {
        "credential_type": "password",
        "id": "crd_sample123456",
        "object": "credential"
      }
    ],
    "custom": {},
    "email": "davy@example.com",
    "email_pending": null,
    "email_verification": "none",
    "first_name": "Davy",
    "id": "usr_sample123456",
    "last_login_at": 1735689600,
    "last_name": "Crockett",
    "locale": null,
    "membership_count": 0,
    "name": "Davy Crockett",
    "object": "user",
    "realm_id": "rl_sample123456",
    "reference": null,
    "state": "active",
    "username": "davy"
  },
  "user_id": "usr_sample123456"
}

On success with MFA, status 200 with a new Token.

{
  "object": "token",
  "token": "tmf:sample123456",
  "user_id": "usr_sample123456"
}

On failure, status 422 with a standard error response.

On success without MFA, returns an object with a new Session.

// console.log(resp.results)
{
  client_app_id: null,
  created_at: 1735689600.0,
  expires_at: 1735776000,
  id: "kss_sample123456",
  object: "session",
  request: {
    client: "user's User-Agent header",
    ip: "10.0.0.1"
  },
  token: "eyJ...",
  user: {
    created_at: 1735689600.0,
    credentials: [
      {
        credential_type: "password",
        id: "crd_sample123456",
        object: "credential"
      }
    ],
    custom: {},
    email: "davy@example.com",
    email_pending: null,
    email_verification: "none",
    first_name: "Davy",
    id: "usr_sample123456",
    last_login_at: 1735689600,
    last_name: "Crockett",
    locale: null,
    membership_count: 0,
    name: "Davy Crockett",
    object: "user",
    realm_id: "rl_sample123456",
    reference: null,
    state: "active",
    username: "davy"
  },
  user_id: "usr_sample123456"
}

On success with MFA, returns an object with a new Token.

// console.log(resp.results)
{
  object: "token",
  token: "tmf:sample123456",
  user_id: "usr_sample123456"
}

On failure, returns an object with a standard error response.

On success without MFA, returns an object with a new Session.

// var_dump($res->fields);
array(9) {
  ["client_app_id"]=> NULL
  ["created_at"]=> float(1735689600.0)
  ["expires_at"]=> int(1735776000)
  ["id"]=> string(16) "kss_sample123456"
  ["object"]=> string(7) "session"
  ["request"]=> 
    array(2) {
      ["client"]=> string(24) "user's User-Agent header"
      ["ip"]=> string(8) "10.0.0.1"
    }
  ["token"]=> string(6) "eyJ..."
  ["user"]=> 
    array(18) {
      ["created_at"]=> float(1735689600.0)
      ["credentials"]=> 
        array(1) {
          [0]=> 
            array(3) {
              ["credential_type"]=> string(8) "password"
              ["id"]=> string(16) "crd_sample123456"
              ["object"]=> string(10) "credential"
            }
        }
      ["custom"]=> array(0) {}
      ["email"]=> string(16) "davy@example.com"
      ["email_pending"]=> NULL
      ["email_verification"]=> string(4) "none"
      ["first_name"]=> string(4) "Davy"
      ["id"]=> string(16) "usr_sample123456"
      ["last_login_at"]=> int(1735689600)
      ["last_name"]=> string(8) "Crockett"
      ["locale"]=> NULL
      ["membership_count"]=> int(0)
      ["name"]=> string(13) "Davy Crockett"
      ["object"]=> string(4) "user"
      ["realm_id"]=> string(15) "rl_sample123456"
      ["reference"]=> NULL
      ["state"]=> string(6) "active"
      ["username"]=> string(4) "davy"
    }
  ["user_id"]=> string(16) "usr_sample123456"
}

On success with MFA, returns an object with a new Token.

// var_dump($res->fields);
array(3) {
  ["object"]=> string(5) "token"
  ["token"]=> string(16) "tmf:sample123456"
  ["user_id"]=> string(16) "usr_sample123456"
}

On failure, returns an object with a standard error response.

On success without MFA, returns an object with a new Session.

AuthRocket::Session(
 client_app_id: nil,
 created_at: 2025-01-01 00:00:00 UTC,
 expires_at: 2025-01-02 00:00:00 UTC,
 id: "kss_sample123456",
 request: {"client"=>"user's User-Agent header", "ip"=>"10.0.0.1"},
 token: "eyJ...",
 user: 
  AuthRocket::User(
   created_at: 2025-01-01 00:00:00 UTC,
   credentials: 
    [AuthRocket::Credential(credential_type: "password", id: "crd_sample123456"
     )],
   custom: {},
   email: "davy@example.com",
   email_pending: nil,
   email_verification: "none",
   first_name: "Davy",
   id: "usr_sample123456",
   last_login_at: 2025-01-01 00:00:00 UTC,
   last_name: "Crockett",
   locale: nil,
   membership_count: 0,
   name: "Davy Crockett",
   realm_id: "rl_sample123456",
   reference: nil,
   state: "active",
   username: "davy"
  ),
 user_id: "usr_sample123456"
)

On success with MFA, returns an object with a new Token.

AuthRocket::Token(token: "tmf:sample123456", user_id: "usr_sample123456")

On failure, raises an exception.

Events

Triggers a user.login.succeeded (no MFA), 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, as started with Authenticate or comparable.

Parameters

ParamValueDefault
token string

Required. The token return by /authenticate above. Starts with tmf:.
code string Required. 6-digit MFA verification code.
expand memberships Include membership and org details in the response.

Request

Example
POST /v2/users/authenticate_token

{
  "request": {
    "client": "user's User-Agent header",
    "ip": "10.0.0.1"
  },
  "user": {
    "code": "123456",
    "token": "tmf:sample123456"
  }
}

var resp = await authrocket.users.authenticateToken({
  code: "123456",
  token: "tmf:sample123456"
})
$res = $authrocket->users->authenticateToken([
  "code" => "123456",
  "token" => "tmf:sample123456"
]);
session = AuthRocket::User.authenticate_token(
  code: "123456",
  token: "tmf:sample123456"
)

Response

Example

On success, status 201 with a new Session.

{
  "client_app_id": null,
  "created_at": 1735689600.0,
  "expires_at": 1735776000,
  "id": "kss_sample123456",
  "object": "session",
  "request": {
    "client": "user's User-Agent header",
    "ip": "10.0.0.1"
  },
  "token": "eyJ...",
  "user": {
    "created_at": 1735689600.0,
    "credentials": [
      {
        "credential_type": "password",
        "id": "crd_sample123456",
        "object": "credential"
      },
      {
        "auth_provider_id": "ap_sample123456",
        "credential_type": "totp",
        "id": "crd_sample123456",
        "name": "device",
        "object": "credential",
        "state": "active"
      }
    ],
    "custom": {},
    "email": "davy@example.com",
    "email_pending": null,
    "email_verification": "none",
    "first_name": "Davy",
    "id": "usr_sample123456",
    "last_login_at": 1735689600,
    "last_name": "Crockett",
    "locale": null,
    "membership_count": 0,
    "name": "Davy Crockett",
    "object": "user",
    "realm_id": "rl_sample123456",
    "reference": null,
    "state": "active",
    "username": "davy"
  },
  "user_id": "usr_sample123456"
}

On failure, status 422 with a standard error response plus retryable which indicates if the token may be retried.

On success, returns an object with a new Session.

// console.log(resp.results)
{
  client_app_id: null,
  created_at: 1735689600.0,
  expires_at: 1735776000,
  id: "kss_sample123456",
  object: "session",
  request: {
    client: "user's User-Agent header",
    ip: "10.0.0.1"
  },
  token: "eyJ...",
  user: {
    created_at: 1735689600.0,
    credentials: [
      {
        credential_type: "password",
        id: "crd_sample123456",
        object: "credential"
      },
      {
        auth_provider_id: "ap_sample123456",
        credential_type: "totp",
        id: "crd_sample123456",
        name: "device",
        object: "credential",
        state: "active"
      }
    ],
    custom: {},
    email: "davy@example.com",
    email_pending: null,
    email_verification: "none",
    first_name: "Davy",
    id: "usr_sample123456",
    last_login_at: 1735689600,
    last_name: "Crockett",
    locale: null,
    membership_count: 0,
    name: "Davy Crockett",
    object: "user",
    realm_id: "rl_sample123456",
    reference: null,
    state: "active",
    username: "davy"
  },
  user_id: "usr_sample123456"
}

On failure, returns an object with a standard error response plus retryable which indicates if the token may be retried.

On success, returns an object with a new Session.

// var_dump($res->fields);
array(9) {
  ["client_app_id"]=> NULL
  ["created_at"]=> float(1735689600.0)
  ["expires_at"]=> int(1735776000)
  ["id"]=> string(16) "kss_sample123456"
  ["object"]=> string(7) "session"
  ["request"]=> 
    array(2) {
      ["client"]=> string(24) "user's User-Agent header"
      ["ip"]=> string(8) "10.0.0.1"
    }
  ["token"]=> string(6) "eyJ..."
  ["user"]=> 
    array(18) {
      ["created_at"]=> float(1735689600.0)
      ["credentials"]=> 
        array(2) {
          [0]=> 
            array(3) {
              ["credential_type"]=> string(8) "password"
              ["id"]=> string(16) "crd_sample123456"
              ["object"]=> string(10) "credential"
            }
          [1]=> 
            array(6) {
              ["auth_provider_id"]=> string(15) "ap_sample123456"
              ["credential_type"]=> string(4) "totp"
              ["id"]=> string(16) "crd_sample123456"
              ["name"]=> string(6) "device"
              ["object"]=> string(10) "credential"
              ["state"]=> string(6) "active"
            }
        }
      ["custom"]=> array(0) {}
      ["email"]=> string(16) "davy@example.com"
      ["email_pending"]=> NULL
      ["email_verification"]=> string(4) "none"
      ["first_name"]=> string(4) "Davy"
      ["id"]=> string(16) "usr_sample123456"
      ["last_login_at"]=> int(1735689600)
      ["last_name"]=> string(8) "Crockett"
      ["locale"]=> NULL
      ["membership_count"]=> int(0)
      ["name"]=> string(13) "Davy Crockett"
      ["object"]=> string(4) "user"
      ["realm_id"]=> string(15) "rl_sample123456"
      ["reference"]=> NULL
      ["state"]=> string(6) "active"
      ["username"]=> string(4) "davy"
    }
  ["user_id"]=> string(16) "usr_sample123456"
}

On failure, returns an object with a standard error response plus retryable which indicates if the token may be retried.

On success, returns an object with a new Session.

AuthRocket::Session(
 client_app_id: nil,
 created_at: 2025-01-01 00:00:00 UTC,
 expires_at: 2025-01-02 00:00:00 UTC,
 id: "kss_sample123456",
 request: {"client"=>"user's User-Agent header", "ip"=>"10.0.0.1"},
 token: "eyJ...",
 user: 
  AuthRocket::User(
   created_at: 2025-01-01 00:00:00 UTC,
   credentials: 
    [AuthRocket::Credential(credential_type: "password", id: "crd_sample123456"
     ),
     AuthRocket::Credential(
      auth_provider_id: "ap_sample123456",
      credential_type: "totp",
      id: "crd_sample123456",
      name: "device",
      state: "active"
     )],
   custom: {},
   email: "davy@example.com",
   email_pending: nil,
   email_verification: "none",
   first_name: "Davy",
   id: "usr_sample123456",
   last_login_at: 2025-01-01 00:00:00 UTC,
   last_name: "Crockett",
   locale: nil,
   membership_count: 0,
   name: "Davy Crockett",
   realm_id: "rl_sample123456",
   reference: nil,
   state: "active",
   username: "davy"
  ),
 user_id: "usr_sample123456"
)

On failure, raises an exception.

Events

Triggers a user.login.succeeded event.

Generate an email verification token

Generates a token for verifying an email address.

Will email the token to the user if a matching Hook exists and is enabled, which is true by default.

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 /v2/users/usr_sample1234556/request_email_verification
POST /v2/users/davy@example.com/request_email_verification

var resp = await authrocket.users.requestEmailVerification("davy@example.com")
$res = $authrocket->users->requestEmailVerification("davy@example.com");
token = AuthRocket::User.request_email_verification "davy@example.com"

Response

Example

On success, status 200 with a new Token.

{
  "object": "token",
  "token": "tve:sample123456",
  "user_id": "usr_sample123456"
}

On failure, status 422 with a standard error response.

On success, returns an object with a new Token.

// console.log(resp.results)
{
  object: "token",
  token: "tve:sample123456",
  user_id: "usr_sample123456"
}

On failure, returns an object with a standard error response.

On success, returns an object with a new Token.

// var_dump($res->fields);
array(3) {
  ["object"]=> string(5) "token"
  ["token"]=> string(16) "tve:sample123456"
  ["user_id"]=> string(16) "usr_sample123456"
}

On failure, returns an object with a standard error response.

On success, returns an object with a new Token.

AuthRocket::Token(token: "tve:sample123456", user_id: "usr_sample123456")

On failure, raises an exception.

Events

Triggers a user.email.verifying event.

Verify an email

Verifies an email address using a previously generated token.

Valid for:

Tokens are valid for 7 days.

If a user’s email (or pending_email) is changed before using the token, the token is invalidated and must be regenerated.

Tokens may be resubmitted, but are a no-op if the email is already marked as verified.

Parameters

ParamValueDefault
token string Required. Email verification token.

Request

Example
POST /v2/users/verify_email

{
  "user": {
    "token": "tve:sample123456"
  }
}

var resp = await authrocket.users.verifyEmail({
  token: "tve:sample123456"
})
$res = $authrocket->users->verifyEmail([
  "token" => "tve:sample123456"
]);
user = AuthRocket::User.verify_email token: "tve:sample123456"

Response

Example

On success, status 200 with the updated User.

{
  "created_at": 1735689600.0,
  "credentials": [
    {
      "credential_type": "password",
      "id": "crd_sample123456",
      "object": "credential"
    }
  ],
  "custom": {},
  "email": "davy@example.com",
  "email_pending": null,
  "email_verification": "verified",
  "first_name": "Davy",
  "id": "usr_sample123456",
  "last_login_at": null,
  "last_name": "Crockett",
  "locale": null,
  "membership_count": 0,
  "name": "Davy Crockett",
  "object": "user",
  "realm_id": "rl_sample123456",
  "reference": null,
  "state": "active",
  "username": "davy"
}

On failure, status 422 with a standard error response.

On success, returns an object with the updated User.

// console.log(resp.results)
{
  created_at: 1735689600.0,
  credentials: [
    {
      credential_type: "password",
      id: "crd_sample123456",
      object: "credential"
    }
  ],
  custom: {},
  email: "davy@example.com",
  email_pending: null,
  email_verification: "verified",
  first_name: "Davy",
  id: "usr_sample123456",
  last_login_at: null,
  last_name: "Crockett",
  locale: null,
  membership_count: 0,
  name: "Davy Crockett",
  object: "user",
  realm_id: "rl_sample123456",
  reference: null,
  state: "active",
  username: "davy"
}

On failure, returns an object with a standard error response.

On success, returns an object with the updated User.

// var_dump($res->fields);
array(18) {
  ["created_at"]=> float(1735689600.0)
  ["credentials"]=> 
    array(1) {
      [0]=> 
        array(3) {
          ["credential_type"]=> string(8) "password"
          ["id"]=> string(16) "crd_sample123456"
          ["object"]=> string(10) "credential"
        }
    }
  ["custom"]=> array(0) {}
  ["email"]=> string(16) "davy@example.com"
  ["email_pending"]=> NULL
  ["email_verification"]=> string(8) "verified"
  ["first_name"]=> string(4) "Davy"
  ["id"]=> string(16) "usr_sample123456"
  ["last_login_at"]=> NULL
  ["last_name"]=> string(8) "Crockett"
  ["locale"]=> NULL
  ["membership_count"]=> int(0)
  ["name"]=> string(13) "Davy Crockett"
  ["object"]=> string(4) "user"
  ["realm_id"]=> string(15) "rl_sample123456"
  ["reference"]=> NULL
  ["state"]=> string(6) "active"
  ["username"]=> string(4) "davy"
}

On failure, returns an object with a standard error response.

On success, returns an object with the updated User.

AuthRocket::User(
 created_at: 2025-01-01 00:00:00 UTC,
 credentials: 
  [AuthRocket::Credential(credential_type: "password", id: "crd_sample123456"
   )],
 custom: {},
 email: "davy@example.com",
 email_pending: nil,
 email_verification: "verified",
 first_name: "Davy",
 id: "usr_sample123456",
 last_login_at: nil,
 last_name: "Crockett",
 locale: nil,
 membership_count: 0,
 name: "Davy Crockett",
 realm_id: "rl_sample123456",
 reference: nil,
 state: "active",
 username: "davy"
)

On failure, raises an exception.

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. User must be active. Password tokens are valid for 3 days.

Multiple tokens may be generated, but once one is used, all existing tokens invalidated. A valid login with the existing password will also invalidate any existing tokens.

Will send the token to the user by email if a matching Hook exists and is enabled, which is true by default.

Request

Example
POST /v2/users/usr_sample1234556/generate_password_token
POST /v2/users/davy@example.com/generate_password_token

var resp = await authrocket.users.generatePasswordToken("davy@example.com")
$res = $authrocket->users->generatePasswordToken("davy@example.com");
token = AuthRocket::User.generate_password_token "davy@example.com"

Response

Example

On success, status 200 with a new Token.

{
  "object": "token",
  "token": "tpw:sample123456",
  "user_id": "usr_sample123456"
}

On failure, status 422 with a standard error response.

On success, returns an object with a new Token.

// console.log(resp.results)
{
  object: "token",
  token: "tpw:sample123456",
  user_id: "usr_sample123456"
}

On failure, returns an object with a standard error response.

On success, returns an object with a new Token.

// var_dump($res->fields);
array(3) {
  ["object"]=> string(5) "token"
  ["token"]=> string(16) "tpw:sample123456"
  ["user_id"]=> string(16) "usr_sample123456"
}

On failure, returns an object with a standard error response.

On success, returns an object with a new Token.

AuthRocket::Token(token: "tpw:sample123456", user_id: "usr_sample123456")

On failure, raises an exception.

Events

Triggers a user.password.resetting event.

Reset password with a token

Validates a password token and resets a user’s password. Also logs the user in by creating a session (or returns an MFA token, if MFA is enabled).

Parameters

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

Request

Example
POST /v2/users/reset_password_with_token

{
  "user": {
    "password": "secret",
    "token": "tpw:sample123456"
  }
}

var resp = await authrocket.users.resetPasswordWithToken({
  password: "secret",
  token: "tpw:sample123456"
})
$res = $authrocket->users->resetPasswordWithToken([
  "password" => "secret",
  "token" => "tpw:sample123456"
]);
session_or_token = AuthRocket::User.reset_password_with_token(
  password: "secret",
  token: "tpw:sample123456"
)

Response

Example

On success without MFA, status 201 with a new Session.

{
  "client_app_id": null,
  "created_at": 1735689600.0,
  "expires_at": 1735776000,
  "id": "kss_sample123456",
  "object": "session",
  "request": {
    "client": "user's User-Agent header",
    "ip": "10.0.0.1"
  },
  "token": "eyJ...",
  "user": {
    "created_at": 1735689600.0,
    "credentials": [
      {
        "credential_type": "password",
        "id": "crd_sample123456",
        "object": "credential"
      }
    ],
    "custom": {},
    "email": "davy@example.com",
    "email_pending": null,
    "email_verification": "none",
    "first_name": "Davy",
    "id": "usr_sample123456",
    "last_login_at": 1735689600,
    "last_name": "Crockett",
    "locale": null,
    "membership_count": 0,
    "name": "Davy Crockett",
    "object": "user",
    "realm_id": "rl_sample123456",
    "reference": null,
    "state": "active",
    "username": "davy"
  },
  "user_id": "usr_sample123456"
}

On success with MFA, status 200 with a new Token.

{
  "object": "token",
  "token": "tmf:sample123456",
  "user_id": "usr_sample123456"
}

On failure, status 422 with a standard error response.

On success without MFA, returns an object with a new Session.

// console.log(resp.results)
{
  client_app_id: null,
  created_at: 1735689600.0,
  expires_at: 1735776000,
  id: "kss_sample123456",
  object: "session",
  request: {
    client: "user's User-Agent header",
    ip: "10.0.0.1"
  },
  token: "eyJ...",
  user: {
    created_at: 1735689600.0,
    credentials: [
      {
        credential_type: "password",
        id: "crd_sample123456",
        object: "credential"
      }
    ],
    custom: {},
    email: "davy@example.com",
    email_pending: null,
    email_verification: "none",
    first_name: "Davy",
    id: "usr_sample123456",
    last_login_at: 1735689600,
    last_name: "Crockett",
    locale: null,
    membership_count: 0,
    name: "Davy Crockett",
    object: "user",
    realm_id: "rl_sample123456",
    reference: null,
    state: "active",
    username: "davy"
  },
  user_id: "usr_sample123456"
}

On success with MFA, returns an object with a new Token.

// console.log(resp.results)
{
  object: "token",
  token: "tmf:sample123456",
  user_id: "usr_sample123456"
}

On failure, returns an object with a standard error response.

On success without MFA, returns an object with a new Session.

// var_dump($res->fields);
array(9) {
  ["client_app_id"]=> NULL
  ["created_at"]=> float(1735689600.0)
  ["expires_at"]=> int(1735776000)
  ["id"]=> string(16) "kss_sample123456"
  ["object"]=> string(7) "session"
  ["request"]=> 
    array(2) {
      ["client"]=> string(24) "user's User-Agent header"
      ["ip"]=> string(8) "10.0.0.1"
    }
  ["token"]=> string(6) "eyJ..."
  ["user"]=> 
    array(18) {
      ["created_at"]=> float(1735689600.0)
      ["credentials"]=> 
        array(1) {
          [0]=> 
            array(3) {
              ["credential_type"]=> string(8) "password"
              ["id"]=> string(16) "crd_sample123456"
              ["object"]=> string(10) "credential"
            }
        }
      ["custom"]=> array(0) {}
      ["email"]=> string(16) "davy@example.com"
      ["email_pending"]=> NULL
      ["email_verification"]=> string(4) "none"
      ["first_name"]=> string(4) "Davy"
      ["id"]=> string(16) "usr_sample123456"
      ["last_login_at"]=> int(1735689600)
      ["last_name"]=> string(8) "Crockett"
      ["locale"]=> NULL
      ["membership_count"]=> int(0)
      ["name"]=> string(13) "Davy Crockett"
      ["object"]=> string(4) "user"
      ["realm_id"]=> string(15) "rl_sample123456"
      ["reference"]=> NULL
      ["state"]=> string(6) "active"
      ["username"]=> string(4) "davy"
    }
  ["user_id"]=> string(16) "usr_sample123456"
}

On success with MFA, returns an object with a new Token.

// var_dump($res->fields);
array(3) {
  ["object"]=> string(5) "token"
  ["token"]=> string(16) "tmf:sample123456"
  ["user_id"]=> string(16) "usr_sample123456"
}

On failure, returns an object with a standard error response.

On success without MFA, returns an object with a new Session.

AuthRocket::Session(
 client_app_id: nil,
 created_at: 2025-01-01 00:00:00 UTC,
 expires_at: 2025-01-02 00:00:00 UTC,
 id: "kss_sample123456",
 request: {"client"=>"user's User-Agent header", "ip"=>"10.0.0.1"},
 token: "eyJ...",
 user: 
  AuthRocket::User(
   created_at: 2025-01-01 00:00:00 UTC,
   credentials: 
    [AuthRocket::Credential(credential_type: "password", id: "crd_sample123456"
     )],
   custom: {},
   email: "davy@example.com",
   email_pending: nil,
   email_verification: "none",
   first_name: "Davy",
   id: "usr_sample123456",
   last_login_at: 2025-01-01 00:00:00 UTC,
   last_name: "Crockett",
   locale: nil,
   membership_count: 0,
   name: "Davy Crockett",
   realm_id: "rl_sample123456",
   reference: nil,
   state: "active",
   username: "davy"
  ),
 user_id: "usr_sample123456"
)

On success with MFA, returns an object with a new Token.

AuthRocket::Token(token: "tmf:sample123456", user_id: "usr_sample123456")

On failure, raises an exception.

Events

Triggers a user.password.updated event and either user.login.succeeded or user.login.initiated. May trigger user.email.verified.

Contents
Fields Required permissions List users Get a user Create a user Update a user Update password Update profile Delete a user Authenticate using a password Complete an MFA authentication Generate an email verification token Verify an email Generate a password token Reset password with a token