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 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 unless generate_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"
}