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. Starts with “crd_”. Example: crd_0v1zUpWdE4IiFc2w5ynShf
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/crd_sample123456

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

Response

Example

Status: 200

{
  "credential_type": "password",
  "id": "crd_sample123456",
  "object": "credential",
  "user_id": "usr_sample123456"
}

// console.log(resp.results)
{
  credential_type: "password",
  id: "crd_sample123456",
  object: "credential",
  user_id: "usr_sample123456"
}
// var_dump($res->fields);
array(4) {
  ["credential_type"]=> string(8) "password"
  ["id"]=> string(16) "crd_sample123456"
  ["object"]=> string(10) "credential"
  ["user_id"]=> string(16) "usr_sample123456"
}
AuthRocket::Credential(
 credential_type: "password",
 id: "crd_sample123456",
 user_id: "usr_sample123456"
)

Create a credential

Create a new credential for a user.

Request

Example
POST /v2/credentials

{
  "credential": {
    "auth_provider_id": "ap_sample123456",
    "credential_type": "totp",
    "name": "phone",
    "user_id": "usr_sample123456"
  }
}

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

Response

Example

On success, status 201 with the new Credential.

{
  "auth_provider_id": "ap_sample123456",
  "credential_type": "totp",
  "id": "crd_sample123456",
  "name": "phone",
  "object": "credential",
  "otp_secret": "SAMPLE",
  "provisioning_svg": "<svg>...</svg>",
  "provisioning_uri": "otpauth://totp/davy?issuer=AcmeApp%20SSO&secret=SAMPLE",
  "state": "new",
  "user_id": "usr_sample123456"
}

On failure, status 422 with a standard error response.

On success, returns an object with the new Credential.

// console.log(resp.results)
{
  auth_provider_id: "ap_sample123456",
  credential_type: "totp",
  id: "crd_sample123456",
  name: "phone",
  object: "credential",
  otp_secret: "SAMPLE",
  provisioning_svg: "<svg>...</svg>",
  provisioning_uri: "otpauth://totp/davy?issuer=AcmeApp%20SSO&secret=SAMPLE",
  state: "new",
  user_id: "usr_sample123456"
}

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

On success, returns an object with the new Credential.

// var_dump($res->fields);
array(10) {
  ["auth_provider_id"]=> string(15) "ap_sample123456"
  ["credential_type"]=> string(4) "totp"
  ["id"]=> string(16) "crd_sample123456"
  ["name"]=> string(5) "phone"
  ["object"]=> string(10) "credential"
  ["otp_secret"]=> string(6) "SAMPLE"
  ["provisioning_svg"]=> string(14) "<svg>...</svg>"
  ["provisioning_uri"]=> string(54) "otpauth://totp/davy?issuer=AcmeApp%20SSO&secret=SAMPLE"
  ["state"]=> string(3) "new"
  ["user_id"]=> string(16) "usr_sample123456"
}

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

On success, returns an object with the new Credential.

AuthRocket::Credential(
 auth_provider_id: "ap_sample123456",
 credential_type: "totp",
 id: "crd_sample123456",
 name: "phone",
 otp_secret: "SAMPLE",
 provisioning_svg: "<svg>...</svg>",
 provisioning_uri: "otpauth://totp/davy?issuer=AcmeApp%20SSO&secret=SAMPLE",
 state: "new",
 user_id: "usr_sample123456"
)

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

Events

Triggers a user.updated event.

Update a credential

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

Request

Example
PUT /v2/credentials/crd_sample123456

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

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

Response

Example

On success, status 200 with the updated Credential.

{
  "credential_type": "password",
  "id": "crd_sample123456",
  "object": "credential",
  "user_id": "usr_sample123456"
}

On failure, status 422 with a standard error response.

On success, returns an object with the updated Credential.

// console.log(resp.results)
{
  credential_type: "password",
  id: "crd_sample123456",
  object: "credential",
  user_id: "usr_sample123456"
}

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

On success, returns an object with the updated Credential.

// var_dump($res->fields);
array(4) {
  ["credential_type"]=> string(8) "password"
  ["id"]=> string(16) "crd_sample123456"
  ["object"]=> string(10) "credential"
  ["user_id"]=> string(16) "usr_sample123456"
}

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

On success, returns an object with the updated Credential.

AuthRocket::Credential(
 credential_type: "password",
 id: "crd_sample123456",
 user_id: "usr_sample123456"
)

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

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/crd_sample123456/verify

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

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

Response

Example

On success, status 200 with the updated Credential.

{
  "auth_provider_id": "ap_sample123456",
  "credential_type": "totp",
  "id": "crd_sample123456",
  "name": "phone",
  "object": "credential",
  "otp_secret": "SAMPLE",
  "provisioning_svg": "<svg>...</svg>",
  "provisioning_uri": "otpauth://totp/davy?issuer=AcmeApp%20SSO&secret=SAMPLE",
  "state": "active",
  "user_id": "usr_sample123456"
}

On failure, status 422 with a standard error response.

On success, returns an object with the updated Credential.

// console.log(resp.results)
{
  auth_provider_id: "ap_sample123456",
  credential_type: "totp",
  id: "crd_sample123456",
  name: "phone",
  object: "credential",
  otp_secret: "SAMPLE",
  provisioning_svg: "<svg>...</svg>",
  provisioning_uri: "otpauth://totp/davy?issuer=AcmeApp%20SSO&secret=SAMPLE",
  state: "active",
  user_id: "usr_sample123456"
}

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

On success, returns an object with the updated Credential.

// var_dump($res->fields);
array(10) {
  ["auth_provider_id"]=> string(15) "ap_sample123456"
  ["credential_type"]=> string(4) "totp"
  ["id"]=> string(16) "crd_sample123456"
  ["name"]=> string(5) "phone"
  ["object"]=> string(10) "credential"
  ["otp_secret"]=> string(6) "SAMPLE"
  ["provisioning_svg"]=> string(14) "<svg>...</svg>"
  ["provisioning_uri"]=> string(54) "otpauth://totp/davy?issuer=AcmeApp%20SSO&secret=SAMPLE"
  ["state"]=> string(6) "active"
  ["user_id"]=> string(16) "usr_sample123456"
}

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

On success, returns an object with the updated Credential.

AuthRocket::Credential(
 auth_provider_id: "ap_sample123456",
 credential_type: "totp",
 id: "crd_sample123456",
 name: "phone",
 otp_secret: "SAMPLE",
 provisioning_svg: "<svg>...</svg>",
 provisioning_uri: "otpauth://totp/davy?issuer=AcmeApp%20SSO&secret=SAMPLE",
 state: "active",
 user_id: "usr_sample123456"
)

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

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/crd_sample123456

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

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