Skip to main content

1Password Events API reference

You can use the 1Password Events API to retrieve information about activity in your 1Password account – like audit events, item usage, and sign-in attempts – and send it to your security information and event management (SIEM) system.

tip

This API reference documents the latest version of the 1Password Events API specifications (1.4.0). Learn more about API versions.

Requirements​

Before you can use the 1Password Events API, you'll need to:

About the API​

The 1Password Events API is a REST-style API that follows the OpenAPI 3.0 Specifications. All communication between clients and servers are over HTTPS.

You can use your preferred language and tools for testing and implementing the Events API. This reference uses curl on the command line to demonstrate example requests. You can replace the values in any request with your own to receive information about events in your 1Password account.

The API can access data from the last 120 days. If you need to access data from more than 120 days ago, you can use the Activity Log in your 1Password account.

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.

  • 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

Servers​

The base URL you'll use to make API calls is determined by the server that hosts your 1Password account.

If your account is on:Your base URL is:
1Password.comhttps://events.1password.com (1Password Business) https://events.ent.1password.com (1Password Enterprise)
1Password.cahttps://events.1password.ca
1Password.euhttps://events.1password.eu

The service ID (events) and the host server form the base URL, followed by the path for the endpoint you want to call. For example, to retrieve a list of audit events for a business account on 1Password.com, you would use the following URL to make a call to the auditevents endpoint:

Authorization​

Every call to the 1Password Events API must be authorized with a bearer token. You must include your bearer token in the header of your request for authentication.

A token can be authorized to access data for one or more events, depending on which events were scoped when the token was created. Make sure the bearer token you use has access to the events you want to request. You can verify this from the Events Reporting integration details in the Integrations section of your 1Password account or through a GET request to the introspection endpoint.

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:

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 can be used 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:

Cursor​

For continued calling of the API, include the cursor from the previous response in the request body of your next call to the API, instead of the ResetCursor object. This will start fetching data from the last indicated position to avoid missing any data.

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

Rate limits​

The Events API limits requests to 600 per minute and up to 30,000 per hour. Exceeding these limits will return an error.

429
Too many requests

GET /api/v2/auth/introspect​

A GET call to this endpoint returns a list of events (features) a bearer token is authorized to access, including one or more of: audit events, item usage, and sign-in attempts.

Parameters​

No parameters.

Requests​

Use the full URL of the introspect endpoint with your bearer token and the required request headers. A GET request doesn't include a body, so the content type header isn't needed.

For example:

Responses​

200
Returns an Introspection object
400
Bad request
401
Unauthorized access
500
Internal server error

A successful 200 response returns an Introspection object with information about the token.

POST /api/v2/auditevents​

A POST call to this endpoint returns information about actions performed by team members within a 1Password account. Events include when an action was performed and by whom, along with details about the type and object of the action and any other information about the activity. MSP accounts include additional information about the actor's account and type. Learn more about audit events.

This endpoint requires a bearer token with the auditevents feature. You can make an introspection call to the API to verify if your token is authorized to access audit events.

Parameters​

No parameters.

Requests​

Use the full URL of the auditevents endpoint with your bearer token and the required request headers. You must include a ResetCursor object or the cursor from a previous response in the request body.

Responses​

A successful 200 response returns an AuditEventItemsV2 object wrapping cursor properties and an array of AuditEventV2 objects. The included cursor can be used to fetch more data or continue the polling process.

200
Returns an AuditEventItemsV2 object
400
Bad request
401
Unauthorized access
500
Internal server error

POST /api/v2/itemusages​

A POST call to this endpoint returns information about items in shared vaults that have been modified, accessed, or used. Events include the name and IP address of the user who accessed the item, when the item was accessed, and the vault where the item is stored. Learn more about item usage actions.

This endpoint requires a bearer token with the itemusages feature. You can make an introspection call to the API to verify if your token is authorized to access sign-in events.

Parameters​

No parameters.

Requests​

Use the full URL of the itemusages endpoint with your bearer token and the required request headers. You must include a ResetCursor object or the cursor from a previous response in the request body.

Responses​

200
Returns an ItemUsageV2 response object
400
Bad request
401
Unauthorized access
500
Internal server error

A successful 200 response returns an ItemUsageItemsV2 object wrapping cursor properties and an array of ItemUsageV2 objects. The included cursor can be used to fetch more data or continue the polling process.

The response also includes a cursor to continue fetching more data or to use the next time you make a request.

POST /api/v2/signinattempts​

A POST call to this endpoint returns information about sign-in attempts. Events include the name and IP address of the user who attempted to sign in to the account, when the attempt was made, and – for failed attempts – the cause of the failure. For MSP accounts, events also include additional information about the user's account and type.

This endpoint requires a bearer token with the signinattempts feature. You can make an introspection call to the API to verify if your token is authorized to access sign-in events.

Parameters​

No parameters.

Requests​

Use the full URL of the signinattempts endpoint with your bearer token and the required request headers. You must include a ResetCursor object or the cursor from a previous response in the request body.

Responses​

200
Returns a SignInAttemptItemsV2 object
400
Bad request
401
Unauthorized access
500
Internal server error

A successful 200 response returns a SignInAttemptItemsV2 object wrapping cursor properties and an array of SignInAttemptV2 objects. The included cursor can be used to fetch more data or continue the polling process.

ErrorResponse object​

Was this page helpful?