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.
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. If not using an official API SDK, remember URL escape the @ character.

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 stored case-sensitive, but unique validations and filtering are handled 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_0v1zTHXhtNgmDaXaDYSAqx

var resp = await authrocket.users.all()
$res = $authrocket->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",
      "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
    }
  ]
}

[ { id: "usr_0v1zUpWdE4IiFc2w5ynShf",
    realm_id: "rl_0v1zTHXhtNgmDaXaDYSAqx",
    username: "dave",
    state: "active",
    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(13) {
      ["id"]=> string(26) "usr_0v1zUpWdE4IiFc2w5ynShf"
      ["realm_id"]=> string(25) "rl_0v1zTHXhtNgmDaXaDYSAqx"
      ["username"]=> string(4) "dave"
      ["state"]=> string(6) "active"
      ["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",
    "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.

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

Parameters

ParamValueDefault
expand hook_states, memberships Include hook state and/or membership+org details in the response. Use a comma for multiple.

Request

Example
GET /v2/users/:user_id
GET /v2/users/:email

var resp = await authrocket.users.find('usr_0v1zUpWdE4IiFc2w5ynShf')
var resp = await authrocket.users.find('dave@example.com')
$res = $authrocket->users->find('usr_0v1zUpWdE4IiFc2w5ynShf');
$res = $authrocket->users->find('dave@example.com');
user = AuthRocket::User.find 'usr_0v1zUpWdE4IiFc2w5ynShf'
user = AuthRocket::User.find 'dave@example.com'

Response

Example

Status: 200

{ "id" : "usr_0v1zUpWdE4IiFc2w5ynShf",
  "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
  "username" : "dave",
  "state" : "active",
  "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"
    }
  ]
}

{ id: "usr_0v1zUpWdE4IiFc2w5ynShf",
  realm_id: "rl_0v1zTHXhtNgmDaXaDYSAqx",
  username: "dave",
  state: "active",
  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(16) {
    ["id"]=> string(26) "usr_0v1zUpWdE4IiFc2w5ynShf"
    ["realm_id"]=> string(25) "rl_0v1zTHXhtNgmDaXaDYSAqx"
    ["username"]=> string(4) "dave"
    ["state"]=> string(6) "active"
    ["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",
    "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.

Parameters

ParamValueDefault
credentials object

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 string

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" : "dave@example.com"
  }
}

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

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:

resp.hasErrors()
// => true
console.log(resp.errors)
// => ["Email can't be blank"]

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(20) "Email 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
# => ["Email can't be blank"]

Events

Triggers a user.created event. May trigger a user.email.verifying or user.email.verified event. When 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 /v2/users/:user_id
PUT /v2/users/:email

{ "user" : {
    "first_name" : "Dave",
    "last_name" : "Smith"
  }
}

var resp = await authrocket.users.update('usr_0v1zUpWdE4IiFc2w5ynShf', {
  first_name: "Dave",
  last_name: "Smith"
})
$res = $authrocket->users->update('usr_0v1zUpWdE4IiFc2w5ynShf', [
  "first_name" => "Dave",
  "last_name" => "Smith"
]);
user = AuthRocket::User.find 'usr_0v1zUpWdE4IiFc2w5ynShf'
user.update 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:

resp.hasErrors()
// => true
console.log(resp.errors)
// => ["Email can't be blank"]

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(20) "Email can't be blank"
  }

On success, returns same object as Get a User.

On failure, returns false:

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

Events

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

Update password

Confirms the existing password and then updates the password.

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/:user_id/update_password
PUT /v2/users/:email/update_password

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

var resp = await authrocket.users.updatePassword('usr_0v1zUpWdE4IiFc2w5ynShf', {
  current_password: "old_secret",
  password: "new_secret",
  password_confirmation: "new_secret"
})
$res = $authrocket->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.

On success, returns same object as Get a User.

On failure, returns an object with errors:

resp.hasErrors()
// => true
console.log(resp.errors)
// => ["Password confirmation does not match"]

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 and user.password.updated event.

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/:user_id/update_profile
PUT /v2/users/:email/update_profile

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

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

Response

Example

Status: 200, with same body as Get a User.
Status: 422 on error validating any field.

On success, returns same object as Get a User.

On failure, returns an object with errors:

resp.hasErrors()
// => true
console.log(resp.errors)
// => ["Email is invalid"]

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(16) "Email is invalid"
  }

On success, returns same object as Get a User.

On failure, returns false:

# => false
user.errors
# => ["Email is invalid"]

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/:user_id
DELETE /v2/users/:email

var resp = await authrocket.users.delete('usr_0v1zUpWdE4IiFc2w5ynShf')
$res = $authrocket->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.

resp.hasErrors()
// => true

On success, returns an object with no errors.

On failure, returns an object with errors.

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

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

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

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

Parameters

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

Request

Example
POST /v2/users/:user_id/authenticate
POST /v2/users/:email/authenticate

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

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

Response

Example

If MFA not enabled, Status: 200 with same body as Get a Session.
If MFA enabled, Status: 200 with:

{ "object" : "token",
  "token" : "...",
  "user_id" : "usr_SAMPLE"
}

Status: 404 if user not found.

On success and MFA not enabled, returns same object as Get a Session.
On success and MFA enabled, returns:

console.log(resp.results)
{ object: "token",
  token: "...",
  user_id: "usr_SAMPLE"
}

If user not found, throws an exception.
On other failure, returns an object with errors.

resp.hasErrors()
// => true

On success and MFA not enabled, returns same object as Get a Session.
On success and MFA enabled, returns:

var_dump($res->fields);
  array(3) {
    ["object"]=> string(5) "token"
    ["token"]=> string(100) "..."
    ["user_id"]=> string(26) "usr_SAMPLE"
  }

If user not found, throws an exception.
On other failure, returns an object with errors.

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

On success and MFA not enabled, returns same object as Get a Session.
On success and MFA enabled, returns:

#<AuthRocket::Token:0x3fde5fa18df8>
  attribs: {
    "object"=>"token",
    "token"=>"...",
    "user_id"=>"usr_SAMPLE"
  }

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 response 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 /v2/users/authenticate_token

{ "user" : {
    "token" : "tmf:76FT6i10aYVh27xXVToHo0",
    "code" : "123456"
  },
  "request" : {
    "ip" : "127.0.0.1",
    "client" : "user's User-Agent header"
  }
}

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

Response

Example

Status: 200 with same body as Get a Session.

On success, returns same object as Get a Session.

On failure, returns an object with errors.

resp.hasErrors()
// => true

On success, returns same object as Get a Session.

On failure, returns an object with errors.

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

On success, returns same object as Get a Session.

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/:user_id/request_email_verification
POST /v2/users/:email/request_email_verification

{ "request" : {
    "ip" : "127.0.0.1"
  }
}

var resp = await authrocket.users.requestEmailVerification('email_or_id', {
  request: {ip: "127.0.0.1"}
})
$res = $authrocket->users->requestEmailVerification('email_or_id', [
  "request" => ["ip" => "127.0.0.1"]
]);
token = AuthRocket::User.request_email_verification 'email_or_id',
 request: {ip: '127.0.0.1'}

Response

Example

Status: 200

{ "object" : "token",
  "token" : "...",
  "user_id" : "usr_SAMPLE"
}

Status: 422 if unable to generate the token.

On success, returns:

console.log(resp.results)
{ object: "token",
  token: "...",
  user_id: "usr_SAMPLE"
}

On failure, returns an object with errors.

On success, returns:

var_dump($res->fields);
  array(3) {
    ["object"]=> string(5) "token"
    ["token"]=> string(100) "..."
    ["user_id"]=> string(26) "usr_SAMPLE"
  }

On failure, returns an object with errors.

On success, returns token object.

#<AuthRocket::Token:0x3fde5fa18df8>
  attribs: {
    "object"=>"token",
    "token"=>"...",
    "user_id"=>"usr_SAMPLE"
  }

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 normal verification tokens (generated by setting email_verification=requested or by API) and preverification tokens (generated by setting email_pending).

Tokens are valid for 7 days from creation.

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

{ "request" : {
    "ip" : "127.0.0.1"
  },
  "user" : {
    "token" : "tve:5Jf0IRSiChW7M2HVqxXujL"
  }
}

var resp = await authrocket.users.verifyEmail({
  token: "tve:5Jf0IRSiChW7M2HVqxXujL",
  request: {ip: "127.0.0.1"}
})
$res = $authrocket->users->verifyEmail([
  "token" => "tve:5Jf0IRSiChW7M2HVqxXujL",
  "request" => ["ip" => "127.0.0.1"]
]);
user = AuthRocket::User.verify_email token: 'tve:5Jf0IRSiChW7M2HVqxXujL',
  request: {ip: '127.0.0.1'}

Response

Example

Status: 200 on success, with same body as Get a User.
Status: 422 if token invalid.

On success, returns same object as Get a User.

On failure, returns an object with errors.

On success, returns same object as Get a User.

On failure, returns an object with errors.

On success, returns same object as Get a User.

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/:user_id/generate_password_token
POST /v2/users/:email/generate_password_token

{ "request" : {
    "ip" : "127.0.0.1"
  }
}

var resp = await authrocket.users.generatePasswordToken('email_or_id', {
  request: {ip: "127.0.0.1"}
})
$res = $authrocket->users->generatePasswordToken('email_or_id', [
  "request" => ["ip" => "127.0.0.1" ]
]);
token = AuthRocket::User.generate_password_token 'email_or_id', request: {ip: '127.0.0.1'}

Response

Example

Status: 200

{ "object" : "token",
  "token" : "...",
  "user_id" : "usr_SAMPLE"
}

Status: 422 if unable to generate the token.

On success, returns:

console.log(resp.results)
{ object: "token",
  token: "...",
  user_id: "usr_SAMPLE"
}

On failure, returns an object with errors.

On success, returns:

var_dump($res->fields);
  array(3) {
    ["object"]=> string(5) "token"
    ["token"]=> string(100) "..."
    ["user_id"]=> string(26) "usr_SAMPLE"
  }

On failure, returns an object with errors.

On success, returns token object:

#<AuthRocket::Token:0x3fde5fa18df8>
  attribs: {
    "object"=>"token",
    "token"=>"...",
    "user_id"=>"usr_SAMPLE"
  }

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.

Parameters

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

Request

Example
POST /v2/users/reset_password_with_token

{ "request" : {
    "ip" : "127.0.0.1"
  },
  "user" : {
    "password" : "secret",
    "password_confirmation" : "secret",
    "token" : "tpw:5Jf0IRSiChW7M2HVqxXujL"
  }
}

var resp = await authrocket.users.resetPasswordWithToken({
  token: "tpw:5Jf0IRSiChW7M2HVqxXujL",
  password: "secret",
  password_confirmation: "secret",
  request: {ip: "127.0.0.1"}
})
$res = $authrocket->users->resetPasswordWithToken([
  "token" => "tpw:5Jf0IRSiChW7M2HVqxXujL",
  "password" => "secret",
  "password_confirmation" => "secret",
  "request" => ["ip" => "127.0.0.1"]
]);
session_or_token = AuthRocket::User.reset_password_with_token(
  token: token,
  password: 'secret',
  password_confirmation: 'secret',
  request: {ip: '127.0.0.1'})

Response

Example

Status: 200 on success, with same body as Authenticate.
Status: 422 for validation error.

On success, returns same object as Authenticate.

On failure, returns an object with errors.

On success, returns same object as Authenticate.

On failure, returns an object with errors.

On success, returns same object as Authenticate.

On failure, raises an exception.

Events

Triggers a user.password.updated event. Might trigger a ‘user.email.verified’ event. Also triggers either user.login.succeeded or user.login.initiated.

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