AuthRocket
These docs are for AuthRocket 1. Looking for AuthRocket 2 docs?

Credentials

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

The allowed types of credentials depend on the user_type of the User.

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 api_key,
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.

api_key only:
api_key string Optional

api_key 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_uri uri Auto-generated

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

Social providers:
auth_provider_id auth_provider_id Auth Provider's ID.
provider_user_id string External provider's Unique ID for this user.
access_token string Access token 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.

API keys

To auto-generate a new API key, set api_key to ‘generate’. When creating a new API key, api_key will also be auto-generated if left blank.

Auto-generated API keys are automatically prefixed with Realm.api_key_prefix, if set. Manually assigned API keys are not auto-prefixed.

API keys can be stored hashed or encrypted. See Realm.api_key_policy for details.

When Realm.api_key_policy is hash, the api_key attribute is only returned when the credential is created or changed (and is then flushed from memory). When Realm.api_key_policy is encrypt, api_key is decrypted and returned every time.

When setting your own value for api_key, please be very careful to use only lengthy, high-entropy keys. If you’re not sure what this means, we strongly urge you to use automatically generated keys instead.

Social providers

Credentials for social 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.

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 /v1/credentials/:credential_id

$res = $client->credentials()->find('crd_0v1zUpWdE4IiFc2w5ynShf');
AuthRocket::Credential.find 'crd_0v1zUpWdE4IiFc2w5ynShf'

Response

Example

Status: 200

{ "id" : "crd_0v1zUpWdE4IiFc2w5ynShf",
  "api_key" : "key-abcdefghijklmnopqrstuvwxyz",
  "credential_type" : "api_key",
  "object" : "credential",
  "user_id" : "usr_0v1zTHXhtNgmDaXaDYSAqx"
}

var_dump($res->fields);
  array(16) {
    ["id"]=> string(26) "crd_0v1zUpWdE4IiFc2w5ynShf"
    ["api_key"]=> string(30) "key-abcdefghijklmnopqrstuvwxyz"
    ["credential_type"]=> string(7) "api_key"
    ["object"]=> string(10) "credential"
    ["user_id"]=> string(26) "usr_0v1zTHXhtNgmDaXaDYSAqx"
  }
#<AuthRocket::Credential:0x3fde5fa18df8>
  id: "crd_0v1zUpWdE4IiFc2w5ynShf",
  attribs: {
    "api_key"=>"key-abcdefghijklmnopqrstuvwxyz",
    "credential_type"=>"api_key",
    "object"=>"credential",
    "user_id"=>"usr_0v1zTHXhtNgmDaXaDYSAqx"
  }

Create a credential

Creates a new credential for a user.

Request

Example
POST /v1/credentials

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

$res = $client->credentials()->create([
  "user_id" => "usr_0v1zTHXhtNgmDaXaDYSAqx",
  "credential_type" => "api_key"
]);
cred = AuthRocket::Credential.create(
  user_id: 'usr_0v1zTHXhtNgmDaXaDYSAqx',
  credential_type: 'api_key'
)

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:

$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 /v1/credentials/:credential_id

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

$res = $client->credentials()->update('crd_0v1zUpWdE4IiFc2w5ynShf', [
  "password" => "secret",
  "password_confirmation" => "secret"
]);
cred=AuthRocket::Credential.find 'crd_0v1zUpWdE4IiFc2w5ynShf'
cred.save 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:

$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 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 /v1/credentials/:credential_id/verify

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

$res = $client->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:

$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 /v1/credentials/:credential_id

$res = $client->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.

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

On success, returns original object.

On failure, returns false.

Events

Triggers a user.updated event.

Questions? Find a Typo? Get in touch.

Back to All Docs