GET v3 audit events (beta) - 1Password Developer

Beta

This API reference documents the latest version of the 1Password Events API beta specification (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, invites another team member to a shared vault, or updates item access permissions.

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.

Authorization: Bearer YOUR_BEARER_TOKEN

Query parameters

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

max_page_size: Specify the maximum number of events records to return per page, between 0 and 1000.
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.
page_token: Use the token value from the next_page_token of the previous response (if provided) and use it with this parameter to fetch the next page of results.

See the query parameters schema for more details.

Example requests

Example request with max_page_size, start_time, and end_time parameters:

curl --request GET \
  --url https://events.1password.com/api/v3/auditevents?max_page_size=50&start_time=2026-05-29T18:00:00Z&end_time=2026-05-29T18:59:59Z \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

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

curl --request GET \
  --url "https://events.1password.com/api/v3/auditevents?page_token=aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK" \
  --header "Authorization: Bearer YOUR_BEARER_TOKEN"

Receive a response

A successful response will include a subset of events matching your query parameters, if any exist. If more results are available, the response will also include a next_page_token at the top level that you can use to request the next page of events. If the next_page_token is absent, that indicates there are no more results for the requested time window. To continue polling for new events, start a new request using the insert_time of the last event as the value for the start_time query parameter. If the response is successful but there aren’t any events for the parameters you requested, the audit_events array will be empty ([]). Learn more about pagination and continuous polling in the beta API.

HTTP status codes

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

Response headers

The response always includes the following HTTP response headers:

Date: The exact date and time the response was generated by the server.
Content-Type: The resource representation format of the response body. This will always be application/json.

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

RateLimit-Limit
RateLimit-Remaining
RateLimit-Reset
Retry-After (only in responses with a 429 Too Many Requests error)

Learn more about rate limits.

Example responses

A successful 200 response returns an AuditEventsResponse object with the following high-level structure:

{
  "audit_events": [
    {
      "action": "string", /* Action taken */
      "actor": { /* Actor object */ },
      "category": "string", /* Category of event */
      "context": { /* Context object */ },
      "correlation_id": "string", /* When applicable */
      "create_time": "string", /* Date and time */
      "diff": { /* Diff object, when applicable */ },
      "insert_time": "string", /* Date and time */
      "targets": [ /* Entity objects */ ],
      "id": "string" /* ID for event */
    }
  ],
  "next_page_token": "string" /* Opaque token */
}

Below is an example of a successful response that shows one event — a user’s vault access was updated to include additional permissions. It includes response headers and metadata with a token to fetch the next page of results.

Example 200 response

HTTP/2 200
date: Fri, 29 May 2026 18:54:52 GMT
content-type: application/json
ratelimit-limit: 600
ratelimit-remaining: 599
ratelimit-reset: 1767735927

{
  "audit_events": [
    {
      "action": "vault.access.update",
      "actor": {
        "email": "wendy_appleseed@agilebits.com",
        "name": "Wendy Appleseed",
        "type": "user",
        "id": "4HCGRGYCTRQFBMGVEGTABYDU2V"
      },
      "category": "vault",
      "context": {
        "account": {
          "name": "AgileBits",
          "id": "VZSYVT2LGHTBWBQGUJAIZVRABM"
        },
        "client": {
          "name": "1Password Extension",
          "version": "81224010"
        },
        "device": {
          "model": "149.0.7827.22",
          "name": "Chrome extension",
          "id": "xa2p3x45d6vbk7noqnom89rxqm"
        },
        "location": {
          "city": "Toronto",
          "ip_address": "192.0.2.254",
          "latitude": 43.6425,
          "longitude": -79.3870,
          "region_code": "CA"
        },
        "origin": "Admin Console",
        "os": {
          "name": "MacOSX",
          "version": "26.5.0"
        },
        "session": {
          "login_time": "2026-05-29T18:29:46.871840158Z",
          "id": "X6TARAEE2NGKFLMK5POQBZ4U2Q"
        },
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36"
      },
      "correlation_id": "BENRUNBI3JCPPLFFRZTQA6XWIZ",
      "create_time": "2026-05-29T18:36:31Z",
      "diff": {
        "new_value": {
          "acl": 15730674,
          "aclDescription": [
            "manage",
            "reveal-password",
            "read-item",
            "update-item",
            "create-item",
            "archive-item",
            "delete-item",
            "view-item-history",
            "send-item"
          ]
        },
        "old_value": {
          "acl": 15730672,
          "aclDescription": [
            "read-item"
          ]
        },
        "type": "user-vault-access-change"
      },
      "insert_time": "2026-05-29T18:36:31.883698939Z",
      "targets": [
        {
          "payload": {
            "type": "U",
            "typeDescription": "user-created",
            "id": "lc5fqgbrcm4plajd8mwncv2b3u"
          },
          "type": "vault"
        },
        {
          "payload": {
            "email": "wendyappleseed+1@1password.com",
            "name": "Wendy Appleseed",
            "id": "OYBARQG5SNEFZHGYT4NDXCHGNI"
          },
          "type": "user"
        }
      ],
      "id": "A5K6COGVRVEJXJW3XQZGS7VAMM"
    }
  ],
  "next_page_token": "eyLMNWdlU2l6ZSI6NSwiU3RhcnRUaW1lIjoiMjAyNS0xMC0wMVQwMDowMDowMFoiLCJFbmRUaW1lIjoiMjAyNi0wMS0wNlQyMTozMzo0Ny44NDA2MjA3NFoiLOPTZWFyY2hBZnRlciI6MTc2MzA2MjYxMjQRSTwiVGllQnJlYWtlciI6IkpaUjdaUVWMN1ZGVDVLVE0zRXYZRURSRlBRIn0"
}

Example response headers when the rate limit has been exceeded:

HTTP/1.1 429 Too Many Requests
content-type: application/json
ratelimit-limit: 600
ratelimit-remaining: 0
ratelimit-reset: 1768325512
retry-after: 60
date: Tue, 13 Jan 2026 17:30:52 GMT

Request schemas

Query parameters

Name	Type	Required	Description
`max_page_size`	integer	No	Maximum number of events records to return per page, from `0` to `1000`. If the `max_page_size` parameter isn’t included (or is set to `0`), the server default of `100` is used. The endpoint accepts any positive value, but returns no more than `1000` events per page.
`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 `page_token`. Doing so will result in a `400` bad request error.
`start_time`	string (date-time)	No	The lower bound insertion time for which to retrieve results, filtering on when events were ingested, not when they occurred. This bound is exclusive: only events whose insertion time is strictly greater than `start_time` are returned. Invalid if `page_token` is specified. Uses the RFC 3339 standard.
`end_time`	string (date-time)	No	The upper bound insertion time for which to retrieve results, filtering on when events were ingested, not when they occurred. This bound is exclusive: only events whose insertion time is strictly less than `end_time` are returned. Invalid if `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
`audit_events`	array	Yes	Array of `AuditEvent` objects. Empty brackets (`[]`) indicate no events match the request.
`next_page_token`	string	No	Opaque token used to retrieve the next page of results. Pass it as the `page_token` query parameter on the next request. Only present when additional pages are available. If the `next_page_token` is absent, that indicates there are no more pages.

AuditEventsResponse: AuditEvent object

Field	Type	Required	Description
`action`	string	Yes	Specific action taken. For example: `report.view`.
`actor`	object	Yes	An `Actor` object describing who initiated the event.
`category`	string	Yes	High-level category of the event. For example: `report`.
`context`	object	Yes	A `Context` object containing information about how the event was initiated.
`correlation_id`	string	No	An optional identifier shared by audit events that originated from the same bulk action. Use it to group related events from a single bulk operation. For example, a bulk user invitation or updating multiple permissions at the same time.
`create_time`	string (date-time)	Yes	The date and time when the event occurred. Uses the RFC 3339 standard.
`diff`	object	No	A `Diff` object describing the change made by the event. Only present for events that represent a change. For example, if a user’s vault access has been updated to add or remove permissions.
`insert_time`	string (date-time)	Yes	The date and time when the event was received and stored by 1Password. The `start_time` and `end_time` query parameters filter on this field. Uses the RFC 3339 standard.
`targets`	array	Yes	Array of `Entity` objects that describe what was affected.
`id`	string	Yes	Unique identifier for the audit event.

AuditEventsResponse: Account object

Field	Type	Required	Description
`id`	string	Yes	ID 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: `domain.com`.

AuditEventsResponse: Actor object

Field	Type	Required	Description
`type`	string	Yes	The type of actor. For example: `user`.
`id`	string	Yes	ID 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.
`user_agent`	string	No	The user agent string reported by the client, when available.

AuditEventsResponse: ContextAccount object

Field	Type	Required	Description
`id`	string	Yes	ID of the account.
`name`	string	Yes	Name of the account.

AuditEventsResponse: Device object

Field	Type	Required	Description
`id`	string	Yes	ID of the device.
`model`	string	Yes	Model of the device.
`name`	string	Yes	Name of the device. For example: `Safari`.

AuditEventsResponse: Diff object

Field	Type	Required	Description
`type`	string	Yes	The type of change made by the event. For example: `account-change`.
`old_value`	object	Yes	The previous value before the change. The shape of the object depends on the `type`.
`new_value`	object	Yes	The new value after the change. The shape of the object depends on the `type`.

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.
`region_code`	string	No	The Unicode CLDR region code associated with the IP address. For example, `CA` for Canada or `DE` for Germany.
`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.
`user_agent`	string	No	Information about the operating system, such as software identification and environment details.

AuditEventsResponse: Session object

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

Error object

Error responses use the standard error shape defined by AEP-193. The type field is a machine-readable error type identifier. The message field is a human-readable description of the error.

Field	Type	Required	Description
`type`	string	Yes	A machine-readable error type identifier. For example: `unauthenticated`.
`message`	string	Yes	A human-readable description of the error.

​Make a request

​Request header

​Query parameters

​Example requests

​Receive a response

​HTTP status codes

​Response headers

​Example responses

​Request schemas

​Query parameters

​Response schemas

​Rate limit headers

​AuditEventsResponse object

​AuditEventsResponse: AuditEvent object

​AuditEventsResponse: Account object

​AuditEventsResponse: Actor object

​AuditEventsResponse: Client object

​AuditEventsResponse: Context object

​AuditEventsResponse: ContextAccount object

​AuditEventsResponse: Device object

​AuditEventsResponse: Diff object

​AuditEventsResponse: Entity object

​AuditEventsResponse: Location object

​AuditEventsResponse: OS object

​AuditEventsResponse: Session object

​Error object

Make a request

Request header

Query parameters

Example requests

Receive a response

HTTP status codes

Response headers

Example responses

Request schemas

Query parameters

Response schemas

Rate limit headers

AuditEventsResponse object

AuditEventsResponse: AuditEvent object

AuditEventsResponse: Account object

AuditEventsResponse: Actor object

AuditEventsResponse: Client object

AuditEventsResponse: Context object

AuditEventsResponse: ContextAccount object

AuditEventsResponse: Device object

AuditEventsResponse: Diff object

AuditEventsResponse: Entity object

AuditEventsResponse: Location object

AuditEventsResponse: OS object

AuditEventsResponse: Session object

Error object