authenticate

The authenticate method verifies a set of user credentials.

📘

Note:

This method allows you to verify a user's credentials. You do not need to issue this request before submitting other methods however, since all methods contain a credentials object.

Syntax

{
	<credentials object>: {
  	"fetch_extra_info": true | false 
  	"generate_session_token": true | false 
  	"token": string 
  	"session_token_duration": "seconds"
}

Request fields for authenticate

The following fields can be used in the authenticate method:

Field nameObligationDefinition/Value
fetch_extra_infoOptionalReturns additional information about the user. If set to true, the response will contain the extra_info field.
generate_session_tokenOptionalIf set to true, returns a session token and the duration of the token.
session_token_durationOptionalThe duration of the session token, in seconds. Value can be a number between 1 and 86400 (24 hours). If not specified, the default is 10800 (3 hours).

Note: This field is ignored unless generate_session_token = true.
tokenOptionalSpecify the token that you want to use. If generate_session_token is true, this string will be used as the token.

Response fields for authenticate

The following fields may be returned in response to the authenticate
method:

Field nameObligationDescription/Value
errorReturned if success = falseA text string that explains the error.
error_numberReturned if success = falseA number that represents the error.
extra_infoReturned if success = true and request contains fetch_extra_info.A list of the user's attributes that may be useful for an interactive client to populate a UI.

For company admins that control multiple companies, the company names listed in "roles" can be used as options for attributes.company in the change_domain call.
session_tokenReturned if success = true and request contains generate_session_token = trueA generated string that can be used in place of the user's password for a limited time. The time begins when the request is submitted and lasts for the number of seconds specified in session_token_duration.
session_token_durationReturned if success = true and request contains generate_session_token = trueThe number of seconds for which the session token is active. If session_token_duration is not specified in the request, this value defaults to 10800 (3 hours); otherwise, it uses the value submitted in the request.
successAlways returnedIndicates whether the request was successful or not. Allowed values are TRUE and FALSE.

Examples for authenticate

Example 1

Request

{
    "credentials": {
        "user": "[email protected]",
        "password": "sw0rdf1sh"
    }
    "fetch_extra_into": true,
    "generate_session_token": true
}

Response

{
    "success": true,
    "extra_info": {
        "roles": {
            "domain": [
                "example.com"
            ]
        },
        "macsettings": "entries_per_page=30;theme=default;search_pages=50;loglevel=90;lang=en; "
    },
    "session_token": "69da1a00117f157537ce785230414ddd",
    "session_token_duration": 10800,
}

Example 2

Request

{
  "credentials": {
    "user": "[email protected]", 
    "password": "pencil75"
  },
  "fetch_extra_info": true,
  "generate_session_token": true,
  "token": "gabbagabba"
}

Response

{ 
"success": true,
  "extra_info": {
    "roles": {
      "domain": [
        "example.com"
      ]
    }, 
    "macsettings": null
  },
  "session_token": "gabbagabba",
  "session_token_duration": 10800,
  "audit": "flesh36_4f183f46b"
}