Auth Object ​

The Auth Object ​

Example Response

{
  "_id": "579b695decea110719b1874d",
  "status": {
    "type": "verified"
  },
  "company": {
    "_id": "579b695decea110719b1874d",
    "name": "Netflix",
    "logo": {
      "url": "https://s3.amazonaws.com/app-assets.unbill.io-primary/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.png",
      "background": false
    }
  }
}

Status Types ​

An auth status.type can be a variety of types. Each type is documented below with a description of the status and a typical use case.

Verified ​

The user's auth has been verified. No actions are required.

For Testing this will happen as long as no other valid auth status is entered.

Verified Response

{
  "status": {
    "type": "verified"
  }
}

Authenticate ​

The auth's credentials are no longer valid and need to be reauthenticated using the Connect product.

For Testing set status to authenticate.

Authenticate Response

{
  "status": {
    "type": "authenticate"
  }
}

Hold ​

An auth's status can be hold for several reasons. When an auth is on hold, the response contains a reason for the hold that you can present to your users. To fix the hold, the user must perform the action described in the reason, which usually requires them to log in to their online account. Once the user has completed the action, make a request to the /auth/{authId}/fix-hold endpoint to resume their services.

Additionally, a code is provided for handling the hold programmatically, if required.

Display hold reason

Displayed after user returns to app

For Testing set status to hold. The account_issue_accept_toc hold code will be placed on the auth.

Hold Response

{
  "status": {
    "type": "hold"
  },
  "reason": {
    "userMessage": "You need to login and verify your account information.",
    "code": "account_issue_verify_identity"
  }
}

MFA Required ​

When the link with a company requires additional MFA.

For Testing set status to mfa-required-questions. Additionally, to test code and prompt based MFA that requires user to be present, use mfa-required-code and mfa-required-prompt in the status field.

MFA Required Response

{
  "status": {
    "type": "mfa-required"
  },
  "mfa": {
    "method": "questions",
    "mfa": [{
      "question": "What city did you grow up in?",
      "identifier": "1j5k2l1"
    },
    {
      "question": "What is your favorite food?",
      "identifier": "3buw78h3"
    }]
  }
}