1Password Events API v3 (beta) - 1Password Developer

The 1Password Events API v3 (version 3) beta is the next version of the 1Password Events API. 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 (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.

Requirements

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

A 1Password Business or 1Password Enterprise Password Manager account (not included with 1Password Teams).
Permissions to manage integrations in your 1Password account (for example, as an owner, administrator, or member of the Security group).

Quickstart

Start here to set up an Events Reporting integration and send your first request to the v3 beta.

Guides

Manage your Events Reporting integrations and issue or revoke bearer tokens.
Read the API conventions to learn how to authenticate, structure requests, and interpret responses and errors.
Track new features and changes in the beta roadmap and changelog.

Reference

Use the API reference to learn more about the v3 beta endpoint.

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 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.

Simpler requests and pagination

The v3 beta follows the API Enhancement Proposal (AEP) design standards. 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 and 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 for your account’s region.	Events API servers 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 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 includes audit events.
Use the same integration for both the v2 and v3 API, but issue separate bearer tokens for each version.
Create separate integrations and bearer tokens for each version.

​Requirements

​Quickstart

​Guides

​Reference

​About the v3 beta API

​A single endpoint for all events

​A consistent event structure

​Simpler requests and pagination

​Compare v2 and v3

​Use v2 and v3 together