> ## Documentation Index
> Fetch the complete documentation index at: https://www.1password.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 1Password Events API v3 (beta)

> Learn about the 1Password Events API v3 beta, how it differs from the v2 Events API, and where to get started.

The 1Password Events API v3 (version 3) beta is the next version of the [1Password Events API](https://www.1password.dev/events-api.md). It's built on an updated audit logging model that gives you a more complete view of the activity in your business or enterprise account. Use the v3 beta to retrieve events from your 1Password account and send them to your security information and event management (SIEM) system.

Instead of calling a separate endpoint for each type of event, the v3 beta brings your account's events together in a single [audit events endpoint](https://www.1password.dev/events-api/beta/reference/get-v3-auditevents.md) (`GET /api/v3/auditevents`). Each event uses the same structured format, so you can see who performed an action, what was affected, and where and how it happened, all in one place.

[Learn more about the beta API.](#about-the-v3-beta-api)

## Requirements

Before you can use the v3 beta, you'll need:

* A [1Password Business](https://1password.com/business-security) or [1Password Enterprise Password Manager](https://1password.com/product/enterprise-password-manager) account (not included with 1Password Teams).
* Permissions to manage integrations in your 1Password account (for example, as an [owner](https://support.1password.com/groups/#owners), [administrator](https://support.1password.com/groups/#administrators), or member of the [Security group](https://support.1password.com/groups/#security)).

## Quickstart

[Start here](https://www.1password.dev/events-api/beta/get-started.md) to set up an Events Reporting integration and send your first request to the v3 beta.

## Guides

* [Manage your Events Reporting integrations](https://www.1password.dev/events-api/beta/manage-integrations.md) and issue or revoke bearer tokens.
* Read the [API conventions](https://www.1password.dev/events-api/beta/conventions.md) to learn how to authenticate, structure requests, and interpret responses and errors.
* Track new features and changes in the [beta roadmap and changelog](https://www.1password.dev/events-api/beta/roadmap.md).

## Reference

Use the [API reference](https://www.1password.dev/events-api/beta/reference.md) to learn more about the v3 beta endpoint.

* [Retrieve audit events](https://www.1password.dev/events-api/beta/reference/get-v3-auditevents.md)
* [Audit events catalog](https://www.1password.dev/events-api/beta/audit-events.md)

## About the v3 beta API

### A single endpoint for all events

The v2 Events API uses individual endpoints for different types of events: `auditevents`, `itemusages`, and `signinattempts`. Each endpoint has its own response schema, so your integration needs to call and process each one separately.

The v3 beta consolidates these with a single `/api/v3/auditevents` endpoint. See the [audit events catalog](https://www.1password.dev/events-api/beta/audit-events.md) for a list of the events the endpoint can return.

### A consistent event structure

Every v3 event uses the same structure, regardless of the type of action. Each event includes:

* An `action` in a `target.attribute.verb` format. For example: `vault.access.update`.
* The `actor` who performed the action, such as a user or a service account.
* The `targets` affected by the action, each with its own type and details.
* The `context` about where and how the action occurred, including the account, client, device, location, operating system, and session.
* A `diff` with the old and new values, for events that represent a change.
* A `correlation_id` to identify audit events that originated from the same bulk action.

Learn more about the [audit event object](https://www.1password.dev/events-api/beta/reference/get-v3-auditevents.md).

### Simpler requests and pagination

The v3 beta follows the [API Enhancement Proposal (AEP) design standards.](https://aep.dev/) Requests use the `GET` method with query parameters, instead of `POST` requests with a cursor object in the request body. Pagination uses a `next_page_token` that's only returned when there are more results to retrieve.

Learn more about [pagination](https://www.1password.dev/events-api/beta/conventions.md#pagination) and [continuous polling](https://www.1password.dev/events-api/beta/conventions.md#continuous-polling) in the v3 beta.

## Compare v2 and v3

| | v2 (production) | v3 (beta) |
| - | - | - |
| **Authorization** | A bearer token scoped to each event type you want to retrieve. | A bearer token scoped to audit events. |
| **Endpoints** | Separate endpoints for each event type: `POST /api/v2/auditevents`, `POST /api/v2/itemusages`, and `POST /api/v2/signinattempts`. | A single endpoint for your account's events: `GET /api/v3/auditevents`. |
| **Base URLs** | [Events API servers](https://www.1password.dev/events-api/servers.md) for your account's region. | [Events API servers](https://www.1password.dev/events-api/beta/conventions.md#base-urls) for your account's region. |
| **Request method** | `POST` with a JSON request body. | `GET` with query parameters. No request body. |
| **Pagination** | A `cursor` and `has_more` flag in the response. Pass the cursor in the request body of the next request. | A `next_page_token` in the response when more results are available. Pass it in the `page_token` query parameter of the next request. |
| **Date and time filters** | `start_time` and `end_time` in the request body. | `start_time` and `end_time` query parameters that filter on when events were ingested by 1Password (`insert_time`). |
| **Response format** | A different schema for each endpoint. | The same structured event schema for every event. |
| **Event timestamps** | A single `timestamp` field. | Separate fields for `create_time` (when the event occurred) and `insert_time` (when 1Password received it). |

## Use v2 and v3 together

The v3 beta uses the same [Events Reporting integrations](https://www.1password.dev/events-api/beta/manage-integrations.md) and bearer tokens as v2. If you want to use the v2 and v3 APIs together, you can choose one of the following options:

* Use the same integration and bearer token for both the v2 and v3 API. Make sure the [token scope](https://www.1password.dev/events-api/beta/manage-integrations.md#token-scopes) includes audit events.
* Use the same integration for both the v2 and v3 API, but [issue separate bearer tokens](https://www.1password.dev/events-api/beta/manage-integrations.md#issue-a-bearer-token) for each version.
* [Create separate integrations](https://www.1password.dev/events-api/beta/manage-integrations.md#create-an-integration) and bearer tokens for each version.


## Related topics

- [1Password Events API beta reference](https://www.1password.dev/events-api/beta/reference.md)
- [API conventions](https://www.1password.dev/events-api/beta/conventions.md)
- [Audit events catalog](https://www.1password.dev/events-api/beta/audit-events.md)