Events API conventions - 1Password Developer

Every request to the 1Password Events API follows the conventions on this page. To authenticate your requests, see Authorization.

Servers and base URLs

The API service ID (events) and the server that hosts your 1Password account form the base URL you’ll use for the API endpoints.

If your account is hosted on:	Your base URL is:
`1password.com`	`https://events.1password.com`
`ent.1password.com`	`https://events.ent.1password.com`
`1password.ca`	`https://events.1password.ca`
`1password.eu`	`https://events.1password.eu`

Endpoints

Endpoint structure

Each API endpoint starts with a base URL, followed by the resource or operation path:

base_url/path

Replace the base_url placeholder with the appropriate base URL for your 1Password account and use the path of the operation or resource you want to access: introspect, auditevents, itemusages, or signinattempts. For example, if your 1Password account is hosted on ent.1password.com and you want to retrieve a list of audit events, you would use the following URL to make a call to the auditevents endpoint:

Structure of an API endpoint

https://events.ent.1password.com/api/v2/auditevents

Endpoint versions

The Events API supports both V1 and V2 endpoints for audit events, item usages, and sign-in attempts. The V2 endpoints in this reference provide additional information about users and accounts for managed service providers (MSPs). V1 endpoints remain fully supported for existing integrations that don’t require the additional MSP account and user type information. Choose the appropriate version based on your needs:

Use V2 endpoints if you need MSP-related event data or if you’re just starting with the Events API.
Use V1 endpoints if you have existing integrations and you don’t require the additional MSP data.

See the API changelog to learn more about the changes in the V2 endpoints and previous versions of the API.

Request methods

The Events API accepts the following standard HTTP request methods:

GET requests to the introspect endpoint return information about the events a bearer token has access to and the account where the token was issued.
POST requests to the auditevents, itemusages, and signinattempts endpoints return information about various activities in a 1Password account. Depending on which endpoint is called, the request returns one of the following:
- Successful and failed attempts to sign in to a 1Password account.
- Information about every use of an item stored in a shared vault in the account.
- Audit events for actions performed by team members in the account.

Request headers

Requests to the Events API must include the correct header(s):

Authorization: Each GET and POST request to the Events API must be authorized with a bearer token scoped to access event data for that feature. You’ll include your token in the authorization header.
Content-Type: Each POST request requires a Content-Type header to indicate the media type of the resource being sent in the request body. All data for the Events API is sent and received as JSON, so you’ll need to specify application/json as the content type. GET requests don’t contain a request body and therefore don’t require this header.

An example of a request header:

Authorization: Bearer YOUR_BEARER_TOKEN
Content-type: application/json

Pagination

The Events API uses cursor-based pagination, which is useful for working with large datasets. In response to each request, the API returns a unique ID (cursor) that indicates where you left off retrieving data. On the next call, you can provide that cursor to continue fetching events starting from the next point in the dataset so no records are missed. There are two types of cursors used in calls to the API: a reset cursor and a cursor (also called a continuing cursor).

Reset cursor

A reset cursor is used for the first request you make to the API to create a new point from which to start fetching data. You can also use a reset cursor any time you need to reset the parameters of your cursor – such as the number of records to return with each request – or go back to an earlier point in the records. For the first POST request you make to the API, you must include a ResetCursor object with an optional start time, end time, and limit parameters in the request body. The return will include a cursor in the response body that you can save to use in the next call made to the API. If no parameters are provided, the API will use the default values indicated in the schema. For example:

Example reset cursor request
ResetCursor object schema

{
	"limit": 100,
	"start_time": "2023-03-15T16:32:50-03:00",
	"end_time": "2023-03-15T17:32:50-03:00"
}

Name	Type	Description
`limit` (optional)	number	The number of events to return in a single request. Specify a limit from 1 to 1000. If not specified, `limit` will default to 100. To return additional events, use the cursor position for subsequent requests.
`start_time` (optional)	string	The date and time to start retrieving events. Uses the RFC 3339 standard. If not specified, `start_time` will default to one hour before specified `end_time`. If no `end_time` is specified, `start_time` will default to one hour ago.
`end_time` (optional)	string	The date and time to stop retrieving events. Uses the RFC 3339 standard.

Cursor

The cursor is a persistent checkpoint that marks your exact position in the event stream and remains valid across API sessions. For continued calling of the API, you should save the cursor you receive from each response. In your next call to the API, include the cursor from the previous response in the request body to start fetching data from the last indicated position. This allows you to resume from where you left off without missing any events.

Example cursor
Cursor object schema

{
	"cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK"
}

Name	Type	Description
`cursor`	string	Cursor to fetch more data, if available, or continue the polling process. Use the cursor returned in the response body of your previous to the endpoint. For example: `aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK`.

The 1Password Events API apps for Splunk and Elastic will automatically store the cursor position for future requests.

Rate limits

The Events API has the following limits:

600 requests per minute
30,000 requests per hour

Exceeding these limits will return the following error:

429 Too many requests

HTTP status codes

Calls to the 1Password Events API may return the following HTTP status codes:

Code	Message	Description / Recommended action
`200`	OK	The request was successful and the server returned a JSON object or an array of objects. Recommended action: No action is required.
`400`	Bad Request	The server could not understand the request due to invalid syntax. Recommended action: Check the API reference and documentation about the API to make sure your request is properly formatted.
`401`	Unauthorized	Authentication has failed or wasn’t provided. Recommended action: Check that your request includes the `Authorization` header, and make sure your bearer token is valid and scoped to access the requested resource. Learn more about authorizing API requests.
`429`	Too Many Requests	The rate limit has been exceeded. Recommended action: Wait until the applicable rate-limit window (per-minute or per-hour) resets, then try again. Learn more about Events API rate limits.
`500`	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request. Recommended action: Retry your request after a brief wait. If the issue persists, check the 1Password status page to verify the Events API service is operational, or contact 1Password Support for help.

​Servers and base URLs

​Endpoints

​Endpoint structure

​Endpoint versions

​Request methods

​Request headers

​Pagination

​Reset cursor

​Cursor

​Rate limits

​HTTP status codes