Credentials

Credentials are tightly associated with Users. All Users have one or more associated Credentials.

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

Credential’s ID. Always starts with “crd_”. Example: crd_USkWvq7fl3LlYPKvqtxBq
user_id user_id Required ID of User this Credential belongs to.
credential_type facebook, github, google, linkedin, oauth2, password, slack, totp, yahoo Required
request hash

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

password only:
password string Required

password type only.
password_confirmation string Optional

password type only.

totp only:
auth_provider_id auth_provider_id Auth Provider's ID.
name string Required Name of the TOTP device, eg: 'iPhone X'.
otp_secret string Auto-generated

The secret used to seed the TOTP device; only when new.
provisioning_svg string Auto-generated

SVG of QRCode for TOTP device self-provisioning; only when new.
provisioning_uri uri Auto-generated

Standardized URI used to create QRCodes for TOTP device self-provisioning; only when new.
state active, new Auto-generated TOTP credentials must be verified prior to becoming active.

Social providers/OAuth2:
access_token string Access token for this user.
auth_provider_id auth_provider_id Auth Provider's ID.
provider_user_id string External provider's Unique ID for this user.
token_expires_at time_t

Expiration time of access_token, if available.

Passwords

password_confirmation is optional when setting/updating a password. If included, it must match password. If not included, the confirmation check is bypassed.

Social providers / OAuth2

Credentials for social providers (and custom OAuth2 providers) are generally handled automatically by LoginRocket or when using the Auth Provider Authenticate with a Token method.

The only method sometimes used with social providers is Delete a Credential.

When migrating existing data to AuthRocket, Create a Credential may be useful. However, you can also skip this and let AuthRocket automatically create the credentials based on matching email addresses.

Required permissions

MethodPermissions
Get read
Create, Update, Verify, Delete write

List credentials

To retrieve all credentials for a user, use Get a User.

Get a credential

Retrieve a specific credential.

Request

Example
GET /v2/credentials/:credential_id

var resp = await authrocket.credentials.find('crd_0v1zUpWdE4IiFc2w5ynShf')
$res = $authrocket->credentials->find('crd_0v1zUpWdE4IiFc2w5ynShf');
cred = AuthRocket::Credential.find 'crd_0v1zUpWdE4IiFc2w5ynShf'

Response

Example

Status: 200

{ "id" : "crd_0v1zUpWdE4IiFc2w5ynShf",
  "credential_type" : "password",
  "object" : "credential",
  "user_id" : "usr_0v1zTHXhtNgmDaXaDYSAqx"
}

console.log(resp.results)
{ id: "crd_0v1zUpWdE4IiFc2w5ynShf",
  credential_type: "password",
  object: "credential",
  user_id: "usr_0v1zTHXhtNgmDaXaDYSAqx"
}
var_dump($res->fields);
  array(16) {
    ["id"]=> string(26) "crd_0v1zUpWdE4IiFc2w5ynShf"
    ["credential_type"]=> string(8) "password"
    ["object"]=> string(10) "credential"
    ["user_id"]=> string(26) "usr_0v1zTHXhtNgmDaXaDYSAqx"
  }
#<AuthRocket::Credential:0x3fde5fa18df8>
  id: "crd_0v1zUpWdE4IiFc2w5ynShf",
  attribs: {
    "credential_type"=>"password",
    "object"=>"credential",
    "user_id"=>"usr_0v1zTHXhtNgmDaXaDYSAqx"
  }

Create a credential

Creates a new credential for a user.

Request

Example
POST /v2/credentials

{ "credential" :
  { "user_id" : "usr_0v1zTHXhtNgmDaXaDYSAqx",
    "credential_type" : "totp"
  }
}

var resp = await authrocket.credentials.create({
  user_id: 'usr_0v1zTHXhtNgmDaXaDYSAqx',
  credential_type: 'totp'
})
$res = $authrocket->credentials->create([
  "user_id" => "usr_0v1zTHXhtNgmDaXaDYSAqx",
  "credential_type" => "totp"
]);
cred = AuthRocket::Credential.create(
  user_id: 'usr_0v1zTHXhtNgmDaXaDYSAqx',
  credential_type: 'totp'
)

Response

Example

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

On success, returns same object as Get a Credential.

On failure, returns an object with errors:

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

On success, returns same object as Get a Credential.

On failure, returns an object with errors:

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

On success, returns same object as Get a Credential.

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

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

Events

Triggers a user.updated event.

Update a credential

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

Request

Example
PUT /v2/credentials/:credential_id

{ "credential" :
  { "password" : "secret",
    "password_confirmation" : "secret"
  }
}

var resp = await authrocket.credentials.update('crd_0v1zUpWdE4IiFc2w5ynShf', {
  password: 'secret',
  password_confirmation: 'secret'
})
$res = $authrocket->credentials->update('crd_0v1zUpWdE4IiFc2w5ynShf', [
  "password" => "secret",
  "password_confirmation" => "secret"
]);
cred = AuthRocket::Credential.find 'crd_0v1zUpWdE4IiFc2w5ynShf'
cred.update password: 'secret', password_confirmation: 'secret'

Response

Example

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

On success, returns same object as Get a Credential.

On failure, returns an object with errors:

resp.hasErrors()
// => true
console.log(resp.errors)
// => ["Password confirmation doesn't match"]

On success, returns same object as Get a Credential.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(35) "Password confirmation doesn't match"
  }

On success, returns same object as Get a Credential.

On failure, returns false:

# => false
credential.errors
# => ["Password confirmation doesn't match"]

Events

Triggers a user.updated event.

For password credentials, does not generate user.password.updated or user.profile.updated events. See also Update Password and Update Profile.

For credentials associated with external providers, depending on which fields are changed, the user.updated event will often be skipped.

Verify a credential

Verify a TOTP credential. If the credential’s state is new, automatically advances to active upon success.

If already active, no changes are made to state, but the code is still verified. This is useful for verifying a user’s 2FA credential prior to performing a sensitive operation inside your app.

Request

Example
POST /v2/credentials/:credential_id/verify

{ "credential" :
  { "code" : "123456"
  }
}

var resp = await authrocket.credentials.verify('crd_0v1zUpWdE4IiFc2w5ynShf', {
  code: '123456'
})
$res = $authrocket->credentials->verify('crd_0v1zUpWdE4IiFc2w5ynShf', [
  "code" => "123456"
]);
cred = AuthRocket::Credential.find 'crd_0v1zUpWdE4IiFc2w5ynShf'
cred.verify '123456'

Response

Example

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

On success, returns same object as Get a Credential.

On failure, returns an object with errors:

resp.hasErrors()
// => true
console.log(resp.errors)
// => ["Verification failed"]

On success, returns same object as Get a Credential.

On failure, returns an object with errors:

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

On success, returns same object as Get a Credential.

On failure, returns false:

# => false
credential.errors
# => ["Verification failed"]

Events

If state changed, triggers a user.updated event. Otherwise, no event is triggered.

Delete a credential

Deletes a credential.

Request

Example
DELETE /v2/credentials/:credential_id

var resp = await authrocket.credentials.delete('crd_0v1zUpWdE4IiFc2w5ynShf')
$res = $authrocket->credentials->delete('crd_0v1zUpWdE4IiFc2w5ynShf');
cred = AuthRocket::Credential.find 'crd_0v1zUpWdE4IiFc2w5ynShf'
cred.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.updated event.

Contents
Fields Required permissions List credentials Get a credential Create a credential Update a credential Verify a credential Delete a credential