> ## 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. # API conventions > Conventions used across the 1Password Events API v3 beta, including authorization, resource paths, query parameters, pagination, rate limits, and error handling. The Events API v3 beta is a REST-style API that supports standard HTTP methods and follows the [OpenAPI 3.0.1 specification.](https://spec.openapis.org/oas/v3.0.1.html) 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](https://datatracker.ietf.org/doc/html/rfc7519) bearer token scoped to include audit events. You'll get a bearer token when you [set up an Events Reporting integration](https://www.1password.dev/events-api/beta/get-started.md#step-1-set-up-an-events-reporting-integration). Send the bearer token in the `Authorization` header of every request, prefixed with `Bearer`: ``` Authorization: Bearer ``` For example: ```shell theme={null} curl --request GET \ --url "https://events.1password.com/api/v3/auditevents" \ --header "Authorization: Bearer " ``` 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](https://www.1password.dev/events-api/beta/manage-integrations.md#manage-bearer-tokens). ## 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](https://support.1password.com/regions/): | Base URL | Description | | - | - | | `https://events.1password.com` | Server for accounts hosted on 1password.com. | | `https://events.ent.1password.com` | Server for accounts hosted on ent.1password.com. | | `https://events.1password.ca` | Server for accounts hosted on 1password.ca. | | `https://events.1password.eu` | Server for accounts hosted on 1password.eu. | > [!NOTE] > > 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](https://www.1password.dev/events-api/beta/roadmap.md) 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: * [`GET /api/v3/auditevents`](https://www.1password.dev/events-api/beta/reference/get-v3-auditevents): Retrieve audit events for actions performed by team members within a 1Password account. To call the endpoint, append the path to your base URL: ```text theme={null} /api/v3/auditevents ``` Check the [API reference documentation](https://www.1password.dev/events-api/beta/reference.md) for more information about the endpoint. ## Requests ### Request methods The beta API currently supports a single HTTP method: | Method | Usage | | - | - | | `GET` | Retrieve audit events. For example: [`GET /api/v3/auditevents`](https://www.1password.dev/events-api/beta/reference/get-v3-auditevents). | > [!NOTE] > > 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](#authentication). ```shell theme={null} Authorization: Bearer ``` ### 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: ```text theme={null} GET https://events.1password.com/api/v3/auditevents?start_time=2026-05-01T00:00:00Z&end_time=2026-06-01T00:00:00Z&max_page_size=100 ``` Check the [API reference documentation](https://www.1password.dev/events-api/beta/reference/get-v3-auditevents.md) 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](#dates-and-times). ### 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. > [!WARNING] > > 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: ```shell theme={null} curl --request GET \ --url "https://events.1password.com/api/v3/auditevents?page_token=CAESCwiY84XSBhC0qu9uGgYIgO600wYg_qXh7fMzKhpXNFRTRVA3UDVSSFBCQUpKM1JDWkdYTFpESQ" \ --header "Authorization: Bearer " ``` 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). #### 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: ```shell theme={null} curl --request GET \ --url "https://events.1password.com/api/v3/auditevents?start_time=2026-05-29T18:36:31.883698939Z" \ --header "Authorization: Bearer " ``` 4. Process the events in the response. If the response includes a `next_page_token`, continue the [pagination workflow](#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. > [!NOTE] > > 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](#errors) and [paginated responses](#pagination). ### Dates and times Every audit event includes two date and time fields, both in [RFC 3339 format](https://datatracker.ietf.org/doc/html/rfc3339): * `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](#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.](https://aep.dev/193/) The `type` field is a machine-readable error type identifier, and the `message` field is a human-readable description of the error. | Status | Meaning | | - | - | | `400 Bad Request` | A request parameter is invalid. For example, `start_time` or `end_time` was sent with `page_token`. | | `401 Unauthorized` | The bearer token is missing, malformed, or invalid. | | `429 Too Many Requests` | The rate limit was exceeded. See [Rate limits](#rate-limits). | | `500 Internal Server Error` | An unexpected error occurred. Retry the request later. | Check the [status codes](https://www.1password.dev/events-api/status-codes.md) page for more information about Events API status codes. ## Related topics - [API conventions](https://www.1password.dev/accounts-api/conventions.md) - [Get started with the 1Password Accounts API for Partners](https://www.1password.dev/accounts-api/get-started.md) - [1Password Accounts API for Partners](https://www.1password.dev/accounts-api.md)