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"
}
Updated less than a minute ago