Gigya Job Openings

audit.search

Skip to end of metadata
Go to start of metadata

Description

The method enables you to search your site's audit log using an SQL-like query. A short delay is possible between the writing of audit log data and its availability in queries.

Only certain APIs and actions are audited (logged). For example, API calls using application keys are not audited. For a complete list of logged APIs, see our Audit Log documentation.

Query Syntax Specification

Gigya queries use the same syntax rules as SQL, however not all standard SQL keywords are available.

  • When querying for text/strings, values must be wrapped in quotes. e.g.,

    SELECT * FROM auditLog WHERE endpoint = "accounts.sociallogin" AND params.x_provider = "facebook"
  • Unsupported SQL syntax in the query string (e.g., HAVING) will produce an error.
  • The query string clauses must be ordered in the following way:
1. SELECT clause
2. FROM clause
3. WHERE clause
4. ORDER BY clause
5. START clause
6. LIMIT clause
  • Encrypted fields are decrypted during searches but comparison operators (>, >=, <, <=) and regex expressions are not available on these fields. The Contains keyword can be used for case-insensitive searches on encrypted fields but does not support partial strings. 

SELECT - The "SELECT" statement may only be used to select all fields ( * ). 

FROM  - Name of the data source. Only one data source is supported. Audit queries must state "FROM auditLog"  (audit.search).

WHERE  - The "WHERE" clause defines conditions for selecting items from the collection. Supported operators:

  • > >=< <= ,  = != - Only = and != can be used with encrypted fields. The "=" operand is case sensitive.
  • AND OR
  • in() - only retrieve items if the field contains one of the list values. For example: 'SELECT * FROM auditLog WHERE errCode in ("0", "400006", "400009")'
  • is null is not null
  • not
  • regex ('<regex-pattern>') - defines a search term using regex formatting. The regex syntax can be found in: Regular Expression Language Reference. Regex patterns cannot be used on encrypted fields.

ORDER BY  - The "order by" clause specifies a list of fields by which to sort the result objects.

LIMIT  - Using the "LIMIT" clause, you may specify the maximum number of returned result objects. If not specified, the default is 300. The maximum limit value accepted is 10000. If the search is sent with openCursor = true, LIMIT will set the batch size. LIMIT must be the last item in the query. Example:

SELECT * FROM auditLog WHERE endpoint = "accounts.sociallogin" LIMIT 1


Please note, when using a cursor, the number of results in a batch is not guaranteed.

START  - The "START" clause (not an SQL standard clause) may be used for paging. The clause specifies the start index from which to return result objects. Start can not be used with openCursor.

The 'SELECT - FROM - WHERE - ORDER BY' query creates an (internal) indexed list of objects. By also using the START & LIMIT clauses, you will receive a subset of this list, starting with the start index and ending with start+limit index.

Note: When implementing paging, there is no guarantee that there will be no duplications or that recently added data will show up in the query results.

 

Fields Available in Audit Log Queries

When querying the Audit Log, you may use the following fields in the WHERE clause:

authType@timestampendpointerrCodeerrMessageerrDetailsipcountry
callIDsdkparamsuserAgentuserKeyuserKeyDetails.emailDomainuserKeyDetails.description 


Request URL


Where <Data_Center> is:
  • us1.gigya.com - For the US data center.
  • eu1.gigya.com - For the European data center.
  • au1.gigya.com - For the Australian data center.
  • ru1.gigya.com - For the Russian data center.
  • cn1.gigya-api.cn - For the Chinese data center.

If you are not sure of your site's data center, see Finding Your Data Center.

Parameters

RequiredNameTypeDescription
querystringThe SQL-like query used to search the audit log. Please refer to the Query language specification above. Note that Gigya field names are case-sensitive, i.e., uid is NOT the same as UID.
             
format string Determines the format of the response. The options are:
  • json (default)
  • jsonp - If the format is jsonp then you are required to define a callback method (see parameter below).
callback string This parameter is relevant only when the format parameter is set to jsonp (see above). In such cases this parameter should define the name of the callback method to be called in the response, along with the jsonp response data.
httpStatusCodes Boolean The default value of this parameter is false, which means that the HTTP status code in Gigya's response is always 200 (OK), even if an error occurs. The error code and message is given within the response data (see below). If this parameter is set to true, the HTTP status code in Gigya's response would reflect an error, if one occurs.
cursorIdstringThe cursor ID that contains the  nextCursorId  value received in the first search call. You cannot pass both cursorId and query on the same request -  cursorId  brings the next page for the search for which it was opened. In addition, the time between search requests using a cursorId  must not exceed 5 minutes.
Each request should contain a different cursorId obtained from the response of the  previous request (not the first) using the nextCursorId field. The exception to this rule is when a request fails or when a particular result set needs to be re-sent; in this case, resend the same cursorID (as long as it has not expired) to receive its associated result set.
openCursorBooleanWhen set to true, the search response will include, in addition to the first page, another field named nextCursorId, which is used to fetch the next batch of results. This parameter should only be used on the first request and later should be removed from the request. When openCursor is true, the Limit  clause sets the number of results returned in the batch.
You cannot use a cursor if you have a group by or when using start.

Unable to render {include} The included page could not be found.

Authorization Parameters

Each REST API request must contain identification and authorization parameters.

Some REST APIs may function without these authorization parameters, however, when that occurs, these calls are treated as client-side calls and all client-side rate limits will apply. In order to not reach client-side IP rate limits that may impact your implementation when using server-to-server REST calls, it is Recommended Best Practice to always sign the request or use a secret. A non-exhaustive list of REST APIs that this may apply to are as follows:

  • accounts.login
  • socialize.login
  • accounts.notifyLogin
  • socialize.notifyLogin
  • accounts.finalizeRegistration
  • accounts.linkAccounts

Please refer to the Authorization Parameters section for details. 

In order to make API calls to audit.search, you must pass a user key, user secret and API key. Partner secrets cannot be used with audit.search.

 

Response Data

FieldTypeDescription
 
errorCode integer The result code of the operation. Code '0' indicates success, any other number indicates failure. For a complete list of error codes, see the Error Codes table.
errorMessage string A short textual description of an error, associated with the errorCode, for logging purposes. This field will appear in the response only in case of an error.
errorDetails string This field will appear in the response only in case of an error and will contain the exception info, if available.
fullEventName string The full name of the event that triggered the response. This is an internally used parameter that is not always returned and should not be relied upon by your implementation.
callId string Unique identifier of the transaction, for debugging purposes.
time string The time of the response represented in ISO 8601 format, i.e., yyyy-mm-dd-Thh:MM:ss.SSSZ or
statusCode integer The HTTP response code of the operation. Code '200' indicates success.
This property is deprecated and only returned for backward compatibility.
statusReason string A brief explanation of the status code.
This property is deprecated and only returned for backward compatibility.

 

objectsCountintegerThe number of objects returned in the "results" array.
totalCountintegerThe total number of objects that satisfy the query in the DB. This is useful when fetching a limited amount using the " limit " parameter.
statusCodeintegerThe HTML status code of the operation.
statusReasonstringA short textual description of the statusCode.
resultsArrayAn array of auditLog objects.

A field that does not contain data will not appear in the response.

Sample Query and Response

Query

SELECT * FROM auditLog WHERE @timestamp > "2014-11-01" AND endpoint LIKE "accounts.%"

 
SELECT * FROM auditLog WHERE endpoint = "accounts.sociallogin" AND params.x_provider = "facebook"

Response

{
  "results": [
     {
      "callID": "***",
      "authType": "everyone",
      "@timestamp": "2018-01-29T11:20:37.095Z",
      "errCode": "0",
      "errMessage": "OK",
      "endpoint": "socialize.login",
      "httpReq": {
        "SDK": "rest"
      },
      "ip": "***.**.***.**",
      "params": {},
      "uid": "***",
      "userAgent": {
        "raw": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.104 Safari/537.36",
        "os": "UNIX",
        "platform": "desktop",
        "browser": "Chrome",
        "language": "en-US,en;q=0.8,la;q=0.6",
        "version": "59.0"
      }
    }
  ],
  "totalCount": 1,
  "statusCode": 200,
  "errorCode": 0,
  "statusReason": "OK",
  "callId": "***",
  "time": "2018-03-06T10:01:55.373Z",
  "objectsCount": 1
}