Get v3 audit events Beta

tip

This API reference documents the latest version of the 1Password Events API beta specifications (3.0.0). Learn more about the beta API.

Retrieve v3 (version 3) audit events for actions performed by team members within a 1Password account.

Method	Endpoint URL
GET	<base_url>/api/v3/auditevents

You can use this endpoint to determine who performed an action and when, like when a team member edits an item's password or invites another team member to a shared vault.

Make a request

Request header

To make a request to the /api/v3/auditevents endpoint, you'll need to use the Authorization header with a bearer token scoped to access audit events.

Query parameters

You can optionally use any of the following query parameters in your request:

• page_size: Specify the number of events records to return per page, between 1 and 1000.
• start_time: The date and time from which to start retrieving events.
• end_time: The date and time to stop retrieving events.
• next_page_token: Add a cursor token from a previous response to go to the next page of results.

See the query parameters schema for more details.

Example requests

Example request with page size and start and end time parameters:

Example request that includes a token to return the next page of events:

Receive a response

A successful response will include a subset of events matching your query parameters (if any exist), along with pagination metadata that indicates if there are more results (true or false). If true, the response will include a token you can use to request subsequent pages of events.

If the response is successful but there aren't any events for the parameters you requested, the audit_events array will be empty ([]).

HTTP status code

Every request returns an HTTP status code that indicates if the response was successful or there was a problem.

Response headers

The response may also include one or more of the following RateLimit response headers, as defined by the IETF standards :

• Content-Type: application/json
• RateLimit-Limit
• Ratelimit-Remaining
• RateLimit-Reset
• Retry-After (only in responses with a 429 Too Many Requests error)

You can use the --include flag in your request to view the HTTP status code and your remaining rate limit in the response. For example:

Example responses

A successful 200 response returns an array of AuditEventsResponse objects with the following high-level structure:

Below is an example of a successful response that shows one event (a user edited an item in a shared vault). It includes response headers and metadata with a token to fetch the next page of results.

Example response headers when the rate limit of 600 requests per minute has been exceeded:

Request schemas

Query parameters

Name	Type	Required	Description
page_size	integer	No	Maximum number of events records to return per page, from 1 to 1000. If the page_size parameter isn't include, the default of 100 will be used.
next_page_token	string	No	Opaque cursor token identifying the next page of results to retrieve. Do not use the start_time or end_time parameters with the next_page_token. Doing so will result in a 400 bad request error.
start_time	string (date-time)	No	The earliest timestamp (inclusive) from which to retrieve events. Invalid if next_page_token is specified. Uses the RFC 3339 standard .
end_time	string (date-time)	No	The latest timestamp (inclusive) for which to retrieve events. Invalid if next_page_token is specified. Uses the RFC 3339 standard .

Response schemas

Rate limit headers

Header	Type	Required	Description
RateLimit-Limit	integer	No	The request quota for the associated client in the current time window.
RateLimit-Remaining	integer	No	The remaining request quota for the associated client.
RateLimit-Reset	integer	No	Unix timestamp that indicates the number of seconds until the request quota is reset for the associated client.
Retry-After	integer	No	Number of seconds until the request quota is reset for the associated client. Only included in responses with the 429 Too Many Requests rate limit error.

AuditEventsResponse object

Field	Type	Required	Description
data	object	Yes	Container for the audit event data.
data.audit_events	array	Yes	Array of AuditEvent objects.
meta	object	Yes	Pagination metadata for the response that can be used in subsequent requests.
meta.next_page_token	string	No	Opaque token used to retrieve the next page of results. Should be included in subsequent requests until has_more is false.
meta.has_more	boolean	Yes	Indicates if additional pages of results are available for retrieval (true) or not (false).

AuditEventsResponse: AuditEvent object

Field	Type	Required	Description
uuid	string	Yes	Unique identifier for the audit event.
timestamp	string (date-time)	Yes	The date and time when the event occurred. Uses the RFC 3339 standard .
context	object	Yes	A Context object containing information about how the event was initiated.
actor	object	Yes	An Actor object describing who initiated the event.
category	string	Yes	High-level category of the event (for example, report).
action	string	Yes	Specific action taken (for example, report.view).
targets	array	Yes	Array of Entity objects that describe what was affected.

AuditEventsResponse: Account object

Field	Type	Required	Description
uuid	string	Yes	UUID of the account.
name	string	Yes	Name of the account.
state	string	Yes	State of the account (for example, A).
type	string	Yes	Type of the account (for example, B).
domain	string	Yes	Domain associated with the account (for example, 1password.com).

AuditEventsResponse: Actor object

Field	Type	Required	Description
type	string	Yes	The type of actor (for example, user).
uuid	string	Yes	UUID of the actor.
name	string	No	Display name of the actor, if available.
email	string	No	Email address of the actor, if available.
linked_account	object	No	An Account object describing a related account, if any.

AuditEventsResponse: Client object

Field	Type	Required	Description
name	string	Yes	Name of the client that was used.
version	string	Yes	Version of the client that was used.

AuditEventsResponse: Context object

Field	Type	Required	Description
account	object	Yes	A ContextAccount object describing the account associated with the event.
origin	string	Yes	The application or interface where the event occurred (for example, password_manager).
session	object	No	A Session object describing the session in which the event occurred.
location	object	Yes	A Location object describing where the event originated.
device	object	No	A Device object describing the device used to initiate the event.
client	object	No	A Client object describing the 1Password client used (app or integration).
os	object	No	An OS object describing the operating system.

AuditEventsResponse: ContextAccount object

Field	Type	Required	Description
uuid	string	Yes	UUID of the account.
name	string	Yes	Name of the account.

AuditEventsResponse: Device object

Field	Type	Required	Description
uuid	string	Yes	UUID of the device.
model	string	Yes	Model of the device.

AuditEventsResponse: Entity object

Field	Type	Required	Description
type	string	Yes	Type of entity affected by a given event. An entity may contain a number of additional properties specific to its type. For example: report, user, or other resource types.
payload	object	Yes	Additional properties describing the entity.

AuditEventsResponse: Location object

Field	Type	Required	Description
ip_address	string	Yes	IP address from which the event originated.
country	string	No	Country associated with the IP address.
region	string	No	Region associated with the IP address.
city	string	No	City associated with the IP address.
latitude	number	No	Latitude of the location.
longitude	number	No	Longitude of the location.

AuditEventsResponse: OS object

Field	Type	Required	Description
name	string	Yes	Name of the operating system that was used.
version	string	Yes	Version of the operating system that was used.
userAgent	string	No	Information about the operating system, such as software identification and environment details.

AuditEventsResponse: Session object

Field	Type	Required	Description
uuid	string	Yes	UUID of the session.
login_time	string (date-time)	Yes	Time when the session was created.

ErrorResponse object

Field	Type	Required	Description
Error	object	No	An Error object containing the error message.

ErrorResponse: Error object

Field	Type	Required	Description
Message	string	No	An error message.