Skip to main content
The Events API v3 beta is a REST-style API that supports standard HTTP methods and follows the OpenAPI 3.0.1 specification. All communication between clients and servers is over HTTPS. The following conventions apply across the v3 beta API, including how to authorize and structure requests, and interpret responses and errors.

​
Authentication

All calls to the v3 beta endpoint must be authenticated with a valid JWT-encoded bearer token scoped to include audit events. You’ll get a bearer token when you set up an Events Reporting integration. Send the bearer token in the Authorization header of every request, prefixed with Bearer:
For example:
If your bearer token is missing, malformed, or invalid, the API returns a 401 Unauthorized response. Learn more about how to manage bearer tokens for Events Reporting integrations.

​
Endpoints

The basic structure of an endpoint URL for the v3 beta API includes the base URL and the endpoint path. The endpoint path includes the API endpoint version and the resource you want to access.

​
Base URLs

The v3 beta endpoint is currently hosted on the same Events API servers as the production API. Use the base URL that matches the region of your 1Password account:
It’s possible these servers could change during the beta or when the v3 endpoint moves to production. You can use the Events API beta roadmap and changelog to track changes.

​
Endpoint paths

Endpoint paths are appended to the base URL and include the endpoint version and the target resource. The v3 beta API has one endpoint: To call the endpoint, append the path to your base URL:
Check the API reference documentation for more information about the endpoint.

​
Requests

​
Request methods

The beta API currently supports a single HTTP method:
The v1 and v2 API endpoints continue to use POST requests with a cursor object in the request body.

​
Request headers

Requests to the beta endpoint require the Authorization header:
  • Authorization: Your bearer token, prefixed with Bearer. Required on every request. See Authentication.

​
Request bodies

The v3 beta endpoint doesn’t use a request body. Pagination and time filters are passed as query parameters.

​
Query parameters

You can use query parameters in your API request as optional modifiers after the endpoint path. Use a query separator (?) at the end of the endpoint path, then add any query parameters you want to include, separated by a query delimiter (&). For example, you can retrieve audit events ingested within a specific time window and set the maximum number of events to return per page:
Check the API reference documentation for more information about the query parameters.

​
Filtering

The /api/v3/auditevents endpoint supports the following date and time parameters:
  • start_time: The earliest insertion time for which to retrieve events (exclusive), filtered on when events were ingested by 1Password. Only events whose insertion time is strictly greater than this value are returned. Invalid if page_token is specified.
  • end_time: The latest insertion time for which to retrieve events (exclusive), filtered on when events were ingested by 1Password. Only events whose insertion time is strictly less than this value are returned. Invalid if page_token is specified.
These parameters filter on the time that events were ingested by 1Password (insert_time), not the time they occurred (create_time). Learn more about dates and times in the API.

​
Pagination

The beta API uses cursor-based pagination. Use the max_page_size and page_token query parameters to page through results:
  • max_page_size: The maximum number of events to return in a single response. If you don’t include max_page_size, or if you set it to 0, the server default of 100 is used. The endpoint accepts any positive value, but it returns no more than 1000 events per page.
  • page_token: An opaque string that identifies the next page of results to retrieve.
Every successful (200) response includes the audit_events array at the top level. If there are more pages of events to retrieve, the response also includes a next_page_token you can pass to the next request. When the response includes a next_page_token, use that token in the page_token query parameter of your next request. You can continue making requests until there are no more events. If a response doesn’t include a token, that indicates there are no more pages of results to retrieve.
Don’t use the start_time or end_time query parameters in a request that also uses the page_token query parameter. Doing so will result in a 400 bad request error.

​
Pagination workflow

The following example shows a typical pagination workflow:
  1. Initial request: Make a GET call to /api/v3/auditevents with any combination of max_page_size, start_time, and end_time parameters you need.
  2. Check the response: Process the audit_events array. Check for a next_page_token at the top level of the response to see if there are more pages. If there’s a token, continue to step 3. If there’s an empty audit_events array with no next_page_token, that means there are no new events yet. Wait and poll again.
  3. Subsequent requests: If there are more pages of events, call the endpoint again using the value of the next_page_token in the page_token query parameter of your next request. For example:
    Repeat this process until the response no longer includes a next_page_token, which means you’ve received all events for the requested time window.
To keep receiving new events as they arrive, see continuous polling.

​
Continuous polling

You can use continuous polling with your integration to call the endpoint on a regular schedule. This allows the integration to retrieve new events as they become available and keep your copy of audit events continuously up to date. To continue the polling loop after the initial pagination is complete:
  1. Record the insert_time of the last event in the response.
  2. Wait until the next scheduled check for new events (the polling interval you set up in your integration).
  3. Make a new request using the recorded insert_time as the start_time parameter. For example:
  4. Process the events in the response. If the response includes a next_page_token, continue the pagination workflow using the page_token query parameter. Otherwise, record the insert_time of the last event in the response and repeat this loop with that value as your new start_time.
No deduplication of the boundary event is required when polling.

​
Responses

The API returns JSON for all responses. A successful request returns 200 OK with an audit_events array at the top level. If more pages of results are available, the response also includes a next_page_token. When there are no events for the parameters you requested, the audit_events array is empty.
The payload object can vary by event type for the items in targets and the old_value and new_value objects in diff. The fields in these objects are specific to each type and might not use the same naming style as the other fields in the response. For example, a diff can include aclDescription rather than acl_description.
Learn more about error responses and paginated responses.

​
Dates and times

Every audit event includes two date and time fields, both in RFC 3339 format:
  • create_time: When the event occurred.
  • insert_time: When the event was received and stored by 1Password.
The start_time and end_time query parameters filter on insert_time, not create_time. This means a single response can include events whose create_time falls outside the query window, as long as the events were ingested within it. This is most likely to happen for events that take time to reach 1Password, such as those from offline clients that sync later. Because the endpoint filters on insert_time, events that arrive later will surface in the next poll that uses a start_time strictly before their insert_time. Your continuous polling loop will receive these events without any special handling.

​
Rate limits

Requests to the beta endpoint are rate limited to:
  • 600 requests per minute
  • 30,000 requests per hour
The API uses standard HTTP headers to communicate your current rate limit window and remaining quota. Responses from GET /api/v3/auditevents may include the following headers:
  • RateLimit-Limit: The total number of requests allowed for the current time window.
  • RateLimit-Remaining: How many requests you can still make in the current window.
  • RateLimit-Reset: The time when the current rate limit window resets, as a Unix timestamp (the number of seconds since January 1, 1970, 00:00:00 UTC). To find how many seconds remain, subtract the current Unix time from this value.
If you exceed the allowed rate, the API returns a 429 Too Many Requests response with a Retry-After header that indicates how many seconds to wait before making another request. When you receive 429 Too Many Requests, you should:
  1. Stop sending additional requests to the endpoint.
  2. Wait for the number of seconds specified in the Retry-After header.
  3. Resume requests, ideally with backoff and retry logic in your client.

​
Errors

The API uses standard HTTP status codes to indicate the result of a request. A 2xx code indicates success. A 4xx code indicates a problem with the request (for example, missing authorization or invalid input). A 5xx code indicates an unexpected server error. Error responses use the standard error shape defined by AEP-193. The type field is a machine-readable error type identifier, and the message field is a human-readable description of the error. Check the status codes page for more information about Events API status codes.