authenticate

📘
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 name	Obligation	Definition/Value
fetch_extra_info	Optional	Returns additional information about the user. If set to true, the response will contain the extra_info field.
generate_session_token	Optional	If set to true, returns a session token and the duration of the token.
session_token_duration	Optional	The 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 unlessgenerate_session_token=true*.
token	Optional	Specify 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 name	Obligation	Description/Value
error	Returned if success = false	A text string that explains the error.
error_number	Returned if success = false	A number that represents the error.
extra_info	Returned 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_token	Returned if success = true and request contains generate_session_token = true	A 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_duration	Returned if success = true and request contains generate_session_token = true	The 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.
success	Always returned	Indicates 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"
}

📘Note:

Request fields for authenticate

Response fields for authenticate

Examples for authenticate

Example 1

Example 2

📘
Note: