# 1Password Events API Documentation
> Events reporting API reference and integration guides.
This file contains all documentation content in a single document following the llmstxt.org standard.
## Audit events
You can use the [1Password Events API](/docs/events-api/reference/) to return audit events from the [audit log](https://support.1password.com/activity-log/) of your 1Password Business account and send them to your security information and event management (SIEM) system. Audit event data includes actions performed by team members in a 1Password account, such as changes made to the account, vaults, groups, users, and more.
## Read an event object
When you use the 1Password Events API to fetch audit events from your 1Password Business account, the API will return a JSON array of [audit event objects](/docs/events-api/reference#post-apiv2auditevents). Event objects can include the following properties:
- **`uuid`**: The unique identifier for the event.
- **`timestamp`**: When the action was performed.
- **`actor_uuid`**: The unique identifier for the team member who performed the action.
- **`actor_details`**: The details of the team member who performed the action (including their UUID, name, and email address).
- **`action`**: The type of action that was performed.
- **`object_type`**: The type of object that the action was performed on.
- **`object_uuid`**: The unique identifier for the object the action was performed on.
- **`object_details`**: The details of the team member who is the object of the action (including their UUID, name, and email address). This property is only returned for events where the object of the action is a team member.
- **`aux_id`**: The identifier that relates to additional information about the activity.
- **`aux_uuid`**: The unique identifier that relates to additional information about the activity.
- **`aux_details`**: The details of the team member who relates to the additional information about the activity (including their UUID, name, and email address). This property is only returned for events where the additional information about an activity relates to a team member.
- **`aux_info`**: Additional information about the activity.
- **`session`**: The information about the session, including the date and time the client signed in and started the session, the unique identifier of the device that signed into the session, and the IP address used.
- **`location`**: The geolocation information of the client based on their IP address at the time the event was performed.
To understand the activity an audit event object is describing, look at the `action`, `actor`, and `object` fields, as well as any `aux` fields that may be included. For example:
```json title="Example audit event object" [{ "badge": 1, "color": "tangerine", "lineNo": 5, "substr": "\\"actor_details\\": {" }, { "badge": 2, "color": "lagoon", "lineNo": 10, "substr": "\\"action\\": \\"join\\"," }, { "badge": 3, "color": "bitsblue", "lineNo": 11, "substr": "\\"object_type\\": \\"gm\\"," }, { "badge": 4, "color": "dahlia", "lineNo": 12, "substr": "\\"object_uuid\\": \\"pf8soyakgngrphytsyjed4ae3u\\"," }, { "badge": 5, "color": "sunbeam", "lineNo": 15, "substr": "\\"aux_details\\": {" }, { "badge": 6, "color": "intrepidblue", "lineNo": 20, "substr": "\\"aux_info\\": \\"A\\","}]
{
"uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E",
"timestamp": "2023-03-15T16:33:50-03:00",
"actor_uuid": "4HCGRGYCTRQFBMGVEGTABYDU2V",
"actor_details": {
"uuid:": "4HCGRGYCTRQFBMGVEGTABYDU2V",
"name": "Jeff Shiner",
"email": "jeff_shiner@agilebits.com"
},
"action": "join",
"object_type": "gm",
"object_uuid": "pf8soyakgngrphytsyjed4ae3u",
"aux_id": 9277034,
"aux_uuid": "K6VFYDCJKHGGDI7QFAXX65LCDY",
"aux_details": {
"uuid": "K6VFYDCJKHGGDI7QFAXX65LCDY",
"name": "Wendy Appleseed",
"email": "wendy_appleseed@agilebits.com"
},
"aux_info": "A",
"session": {
"uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM",
"login_time": "2023-03-15T16:33:50-03:00",
"device_uuid": "lc5fqgbrcm4plajd8mwncv2b3u",
"ip": "192.0.2.254"
},
"location": {
"country": "Canada",
"region": "Ontario",
"city": "Toronto",
"latitude": 43.5991,
"longitude": -79.4988
}
}
```
This example event shows that Jeff Shiner is the actor who performed the "join" action on a [group membership](#group-membership) (Jeff added someone to a group). And Wendy Appleseed is the team member who joined (was added to) the Administrator group as a [group manager](#group-membership).
To get more information about an object, such as the name of a group, you can check the description of the event in the [audit log](https://support.1password.com/activity-log/), or use the object UUID to [retrieve information about an object with 1Password CLI](/docs/cli/reference#unique-identifiers-ids).
Use the audit event tables below to learn more about what the different actions and objects mean and what output is returned for each type of event. A complete list of actions and objects can be found in the [appendix](#appendix).
## Audit events
- [Accounts](#accounts)
- [Delegate sessions](#delegate-sessions)
- [Devices](#devices)
- [Email changes](#email-changes)
- [Family accounts](#family-accounts)
- [Files](#files)
- [Firewall rules](#firewall-rules)
- [Groups](#groups)
- [Group membership](#group-membership)
- [Group vault access](#group-vault-access)
- [Invites](#invites)
- [Items](#items)
- [Item sharing](#item-sharing)
- [Managed companies](#managed-companies)
- [Multi-factor authentication](#multi-factor-authentication)
- [Packages](#packages)
- [Provisioning](#provisioning)
- [Reports](#reports)
- [Service accounts](#service-accounts)
- [Service account tokens](#service-account-tokens)
- [Sign-in tokens](#sign-in-tokens)
- [Slack app](#slack-app)
- [SSO settings](#sso-settings)
- [Stripe cards](#stripe-cards)
- [Stripe payment methods](#stripe-payment-methods)
- [Stripe subscriptions](#stripe-subscriptions)
- [Templates](#templates)
- [Unknown](#unknown)
- [Users](#users)
- [User vault access](#user-vault-access)
- [User WebAuthn credentials (passkeys)](#passkeys)
- [Vaults](#vaults)
- [Verified domain](#verified-domain)
### Accounts
Actions related to updating and confirming accounts.
Event
Description
Action
Object Type
Aux Info
Activate Account
The account was activated.
`activate`
`account`
Update Account
Account attributes, such as the name, were changed.
`update`
`account`
Delete Account
The account was deleted.
`delete`
`account`
Update Account Domain
The account domain was changed.
`update`
`account`
domain
Change Account Type
The account type was changed.
`convert`
`account`
old account type, new account type
`I`: Individual account
`F`: Family account
`B`: Business account
Enable Duo
Duo was enabled for the account.
`enblduo`
`account`
Update Duo Configuration
The Duo configuration for the account was updated.
`updatduo`
`account`
Disable Duo
Duo was disabled for the account.
`disblduo`
`account`
### Delegate sessions
Actions related to delegating sessions.
Event
Description
Action
Object type
Aux info
Delegate Session
A new delegated session was added.
`dlgsess`
`dlgdsess`
session UUID
### Devices
Actions related to authorizing and removing devices.
Event
Description
Action
Object Type
Aux Info
Add Device
A device was added to the account.
`create`
`device`
user ID, user UUID, user name, user email
Update Device
A device was updated.
`update`
`device`
user ID, user UUID, user name, user email
Delete Device
A device was deleted.
`delete`
`device`
user ID, user UUID, user name, user email
Delete Old Devices
Old devices were deleted.
`deolddev`
`user`
Delete All Devices
All devices were deleted.
`dealldev`
`user`
Reauthorize Device
A device was reauthorized after being deauthorized
`reauth`
`device`
user ID, user UUID, user name, user email
### Email changes
Actions related to beginning and completing email changes for team members.
Event
Description
Action
Object Type
Aux Info
Begin Email Change
An email change was requested by a user.
`begin`
`ec`
Complete Email Change
A user's email was changed.
`complete`
`ec`
Propose Email Change
An email change was proposed by an admin.
`propose`
`ec`
### Family accounts
Actions related to linking and unlinking family accounts.
Event
Description
Action
Object Type
Aux Info
Add Family Member Account
A team member linked their free family account.
`rdmchild`
`famchild`
Remove Family Member Account
A team member unlinked their free family account.
`detchild`
`famchild`
### Files
Actions related to creating documents.
Event
Description
Action
Object Type
Aux Info
Add File
A file was uploaded to the account.
`create`
`file`
### Firewall rules
Actions related to firewall settings.
Event
Description
Action
Object type
Aux info
Update Firewall Rules
A firewall rule was added or updated.
`updatfw`
`account`
### Groups
Actions related to creating, updating, and removing groups.
Event
Description
Action
Object Type
Aux Info
Create Group
A group was created.
`create`
`group`
group name
Available for events that occurred after June 11, 2025.
Delete Group
A group was deleted.
`delete`
`group`
group name
Update Group
A group was updated.
`update`
`group`
group name
Purge Deleted Group
A group was marked to be purged.
`purge`
`group`
Update Group Keyset
A group keyset was replaced.
`changeks`
`group`
### Group membership
Actions related to updating team members' group membership.
Event
Description
Action
Object Type
Aux Info
Join Group
A user joined a group.
`join`
`gm`
user ID, user UUID, user name, user email, user role
`R`: Group member
`A`: Group manager
Leave Group
A user left a group.
`leave`
`gm`
user ID, user UUID, user name, user email
Change Group Membership Role
A user's group membership role was changed.
`role`
`gm`
user ID, user UUID, user name, user email, user role
`R`: Group member
`A`: Group manager
### Group vault access
Actions related to modifying groups' access to vaults.
Event
Description
Action
Object Type
Aux Info
Grant Group Vault Access
A group was granted access to a vault.
`grant`
`gva`
group ID, group UUID, Access Control List
Revoke Group Vault Access
A group's access to a vault was revoked.
`revoke`
`gva`
group ID, group UUID
Update Group Vault Access
A group's vault access was updated.
`update`
`gva`
group ID, group UUID, Access Control List
### Invites
Actions related to inviting team members and guests.
Event
Description
Action
ObjectType
AuxInfo
Create Invite
An invite was created.
`create`
`invite`
The email address the invite was sent to.
Update Invite
An invite was updated.
`update`
`invite`
The email address the invite was sent to.
### Items
Actions related to creating, editing, archiving, and deleting items.
Event
Description
Action
ObjectType
AuxInfo
Patch Vault Items
Vault items were added or updated.
`patch`
`items`
Vault Content Version, number of items added or updated.
Delete Trashed Vault Items
Vault items in the trash were deleted.
`delete`
`items`
Vault Content Version, number of items deleted.
Purge Deleted Vault Items
Deleted vault items were marked to be purged.
`purge`
`items`
Number of items that were marked to be purged.
Purge Vault Item History
Archived vault items were marked to be purged.
`purge`
`itemhist`
item ID, item UUID
### Item sharing
Actions related to [sharing items](https://support.1password.com/share-items/).
Event
Description
Action
Object Type
Aux Info
Share Item
An item was shared externally.
`share`
`item`
vault ID, vault UUID, shared item UUID
Delete Item Share
A shared item link was deleted.
`delshare`
`item`
vault ID, vault UUID, shared item UUID
Update Item Share Settings
The account's item sharing settings were updated.
`uisas`
`account`
### Managed companies
Actions related to a managed service provider (MSP) creating, launching into, and unlinking managed companies.
Event
Description
Action
Object Type
Aux Info
Add Managed Company
A managed company was added to an MSP account.
`create`
`mngdacc`
Launch Into Managed Company
An MSP technician launched into a managed company.
`launchi`
`mngdacc`
The ID and UUID of the launched session.
Unlink Managed Company
A managed company was unlinked from an MSP account.
`unlink`
`mngdacc`
### Multi-factor authentication
Actions related to enabling, updating, and removing multi-factor authentication.
Event
Description
Action
Object Type
Aux Info
Enable Multi-Factor Authentication
Multi-factor authentication was enabled.
`enblmfa`
`user`
multi-factor authentication ID, multi-factor authentication type
Update Multi-Factor Authentication
Multi-factor authentication was updated.
`updatmfa`
`user`
multi-factor authentication ID, multi-factor authentication type
Disable Multi-Factor Authentication
Multi-factor authentication was disabled.
`disblmfa`
`user`
multi-factor authentication ID, multi-factor authentication type
Disable Multi-Factor Authentication For All Users
Multi-factor authentication was disabled for everyone in the account.
`disblmfa`
`account`
Disable Multi-Factor Authentication Type For All Users
Multi-factor authentication of a certain type was disabled for everyone in the account.
`disblmfa`
`account`
multi-factor authentication type
### Packages
Actions related to team members sending a copy of an item within 1Password.
Event
Description
Action
Object Type
Aux Info
Send Package
A user sent an item to another user.
`sendpkg`
`user`
package UUID
### Provisioning
Actions related to provisioning new team members.
Event
Description
Action
Object Type
Aux Info
Send Provisioning Email
A provisioning email was sent.
`sendts`
`user`
Resend Provisioning Email
A provisioning email was resent.
`resendts`
`user`
Resend All Provisioning Emails
All provisioning emails were resent.
`prsndall`
`invite`
### Reports
Actions related to viewing and exporting reports.
Event
Description
Action
ObjectType
AuxInfo
Export Report
A user exported a report.
`export`
`report`
report UUID, report type
View Report
A user viewed a report.
`view`
`report`
report UUID, report type
### Service accounts
Actions related to adding service accounts.
Event
Description
Action
Object Type
Aux Info
Create Integration
A service account was created.
`create`
`sa`
The type of service account.
Set Expiration Integration
An expiration time was set for a user-managed service account.
`expire`
`sa`
The type of service account.
### Service account tokens
Actions related to registering, updating, and revoking access tokens for service accounts.
Event
Description
Action
Object Type
Aux Info
Create Token
A service account token was registered.
`create`
`satoken`
token name
Rename Token
A service account token name was updated.
`trename`
`satoken`
token name
Verify Token
A service account token signature was registered.
`tverify`
`satoken`
token name
Revoke Token
A service account token was revoked.
`trevoke`
`satoken`
token name
### Sign-in tokens
Actions related to creating, ratcheting, and signing in with sign-in tokens for Unlock with SSO.
Event
Description
Action
Object Type
Aux Info
Sign In With Sign-In Token
A sign-in token was used to log in.
`ssotknv`
`ssotkn`
### Slack app
Actions related to connecting or removing a Slack app.
Event
Description
Action
Object Type
Aux Info
Enable Slack App
A Slack app was connected to the account.
`create`
`slackapp`
Disable Slack App
A Slack app was removed from the account.
`delete`
`slackapp`
Update Slack App
A connected Slack app was updated.
`update`
`slackapp`
### SSO settings
Actions related to setting up [Unlock with SSO](https://support.1password.com/sso-get-started/).
Event
Description
Action
Object Type
Aux Info
Enable SSO
Unlock with SSO was enabled.
`enblsso`
`sso`
Disable SSO
Unlock with SSO was disabled.
`disblsso`
`sso`
Change SSO Authentication Policy
The SSO authentication policy was changed.
`chngpsso`
`sso`
Change SSO Grace Period Authentication Count
The SSO grace period authentication count was changed.
`chngasso`
`sso`
Change SSO Grace Period Duration
The SSO grace period duration was changed.
`chngdsso`
`sso`
Add an SSO Group.
An SSO group was added.
`addgsso`
`sso`
group UUID
Delete an SSO Group.
An SSO group was deleted.
`delgsso`
`sso`
group UUID
### Stripe cards
Actions related to creating, updating, and removing Stripe cards.
Event
Description
Action
Object Type
Aux Info
Add Card
A new Stripe card was created.
`create`
`card`
card ID, card UID
Update Card
A Stripe card was updated.
`update`
`card`
card ID, card UID
Delete Card
A Stripe card was deleted.
`delete`
`card`
card ID, card UID
### Stripe payment methods
Actions related to adding Stripe payment methods.
Event
Description
Action
Object Type
Aux Info
Add Payment Method
A new Stripe payment method was created.
`create`
`pm`
payment method ID, payment method UUID
Delete Payment Method
A Stripe payment method was deleted.
`delete`
`pm`
payment method ID, payment method UUID
### Stripe subscriptions
Actions related to creating, updating, and canceling Stripe subscriptions.
Event
Description
Action
Object Type
Aux Info
Create Subscription
A new Stripe subscription was created.
`create`
`sub`
subscription ID, subscription UUID
Update Subscription
A Stripe subscription was updated.
`update`
`sub`
subscription ID, subscription UUID
Cancel Subscription
A Stripe subscription was canceled.
`cancel`
`sub`
subscription ID, subscription UUID
### Templates
Actions related to adding, updating, hiding, and deleting templates.
Event
Description
Action
Object Type
Aux Info
Add Template
A template was added.
`create`
`template`
template name
Update Template
A template was updated.
`update`
`template`
template name
Hide Template
A template was hidden.
`hide`
`template`
template name
Unhide Template
A template was shown (after being hidden).
`unhide`
`template`
template name
Delete Template
A template was deleted.
`delete`
`template`
template name
### Unknown
Unknown events.
Event
Description
Action
ObjectType
AuxInfo
Unknown Events
An unknown action occurred.
`unknown`
`unknown`
### Users
Actions related to changes to team members' accounts attributes.
Event
Description
Action
Object Type
Aux Info
Upgrade User
A guest was promoted to a family or team member.
`upguest`
`user`
Change User State From
A user's state was changed.
`verify`, `join`, `activate`, `reactive`, `suspend`, `delete`, or `beginr`
`user`
Begin User Recovery
A user recovery was initiated.
`beginr`
`user`
Complete User Recovery
A user recovery was completed.
`completr`
`user`
Cancel User Recovery
A user recovery was canceled.
`cancelr`
`user`
Mark User Away For Travel
A user was marked as away for travel.
`trvlaway`
`user`
Mark User Back From Travel
A user was marked as back from travel.
`trvlback`
`user`
Change User Keyset
A user's keyset changed.
`changeks`
`user`
Change 1Password Account Password
A user changed their 1Password account password.
`changemp`
`user`
Change Secret Key
A user changed their Secret Key.
`changesk`
`user`
Change Name
A user changed their name.
`changenm`
`user`
Change Language
A user changed their preferred language.
`changela`
`user`
Enroll Trusted Device
A user set up a trusted device to unlock with SSO.
`tdvcsso`
`user`
device UUID
Set up Single Sign-On Authentication
A user set up their 1Password account to unlock with SSO.
`sdvcsso`
`user`
### User migration
Actions related to migrating users.
Event
Description
Action
Object Type
Aux Info
Migrating User Created
A user migration was started.
`create`
`miguser`
user email
Migrating User Complete
A user migration was marked complete.
`musercom`
`miguser`
Migrating User Declined
A user migration was marked declined.
`muserdec`
`miguser`
### User vault access
Actions related to changes to team members' access to vaults.
Event
Description
Action
Object Type
Aux Info
Grant User Vault Access
A user was granted access to a vault.
`grant`
`uva`
user ID, user UUID, user name, user email, Access Control List
Revoke User Vault Access
A user's access to a vault was revoked.
`revoke`
`uva`
user ID, user UUID, user name, user email
Update User Vault Access
A user's vault access was updated.
`update`
`uva`
user ID, user UUID, user name, user email, Access Control List
### User WebAuthn credentials (passkeys) {#passkeys}
Actions relating to creating and deleting [passkeys](https://support.1password.com/save-use-passkeys/) used to sign in to 1Password.
Event
Description
Action
Object Type
Aux Info
Create User Webauthn Credential
A passkey was created to sign in to 1Password.
`create`
`cred`
Delete User Webauthn Credential
A passkey used to sign in to 1Password was deleted.
`delete`
`cred`
### Vaults
Actions related to creating, updating, and removing vaults.
Event
Description
Action
Object Type
Aux Info
Add Vault
A vault was added.
`create`
`vault`
Delete Vault
A vault was deleted.
`delete`
`vault`
Mark Vault To Be Purged
A vault was marked for purging.
`purge`
`vault`
Update Client Access
The client access value for a vault was updated.
`update`
`vault`
The new client access value.
Update Attributes
A vault name or description was changed.
`updatea`
`vault`
Export Vault
A vault was exported.
`export`
`vault`
### Verified domain
Actions related to verifying domains.
Event
Description
Action
ObjectType
AuxInfo
Add Verified Domain
A domain was verified.
`vrfydmn`
`account`
domain
Update Verified Domain
A verified domain was updated.
`uvrfydmn`
`account`
domain
Delete Verified Domain
A verified domain was removed.
`dvrfydmn`
`account`
domain
## Appendix
### Action values
Possible values for `action` include:
API output
Action
`activate`
Activate
`addgsso`
Add an SSO group
`begin`
Begin
`beginr`
Begin recovery
`cancel`
Cancel
`cancelr`
Cancel recovery
`changeks`
Change keyset
`changela`
Change language
`changemp`
Change 1Password account password
`changenm`
Change name
`changesk`
Change Secret Key
`chngasso`
Change SSO grace period authentication count
`chngdsso`
Change SSO authentication policy
`chngpsso`
Change SSO grace period duration
`complete`
Complete
`completr`
Complete recovery
`convert`
Convert
`create`
Create
`dealldev`
Deauthorize all devices
`delete`
Delete
`delgsso`
Delete an SSO Group
`delshare`
Delete shared item link
`deolddev`
Deauthorize old devices
`detchild`
Remove family member account
`disblduo`
Disable Duo
`disblmfa`
Disable multi-factor authentication
`disblsso`
Disable SSO
`dlgsess`
Delegate a new session
`dvrfydmn`
Delete verified domain
`enblduo`
Enable Duo
`enablmfa`
Enable multi-factor authentication
`enblsso`
Enable SSO
`expire`
Expire
`export`
Export
`grant`
Grant
`hide`
Hide
`join`
Join
`launchi`
Launch into managed company
`leave`
Leave
`musercom`
Complete migrating user
API output
Action
`muserdec`
Decline migrating user
`patch`
Modify or update
`propose`
Propose
`provsn`
Provision
`prsndall`
Resend all provisioning emails
`purge`
Permanently delete
`rdmchild`
Add family member account
`reactive`
Reactivate
`reauth`
Reauthorize
`resendts`
Resend provisioning email
`revoke`
Revoke
`role`
Update group membership role
`sdvcsso`
Set up SSO authentication
`sendpkg`
Send an item to another user
`sendts`
Send provisioning email
`share`
Share an item externally
`ssotkn`
Create sign-in token
`ssotknr`
Ratchet sign-in token
`ssotknv`
Sign in with sign-in token
`suspend`
Suspend
`tdvcsso`
Enroll trusted device
`trename`
Rename token
`trevoke`
Revoke token
`trvlaway`
Set as away for travel
`trvlback`
Set as back from travel
`tverify`
Verify token signature
`uisas`
Update item sharing administrator settings
`unhide`
Unhide
`unknown`
Unknown
`unlink`
Unlink managed company
`updatduo`
Update Duo
`update`
Update
`updatea`
Update attributes
`updatfw`
Update firewall rules
`updatmfa`
Update multi-factor authentication
`upguest`
Update guest
`uvrfydmn`
Update verified domain
`view`
View
`verify`
Verify
`vrfydmn`
Add verified domain
### Object values
Possible values for `objectType` include:
API output
Object
`account`
1Password account
`card`
Stripe card
`cred`
Credentials
`device`
Device
`dlgdsess`
Delegated session
`ec`
Email change
`famchild`
Linked family account
`file`
File
`gm`
Group membership
`group`
Group
`gva`
Group vault access
`invite`
Invite
`item`
Item
`itemhist`
Item history
`items`
Items
`mngdacc`
Managed account
`miguser`
Migrating user
API output
Object
`mngdacc`
Managed account
`miguser`
Migrating user
`plan`
Plan
`pm`
Stripe payment method
`report`
Report
`sa`
Service account
`satoken`
Service account token
`slackapp`
Slack app
`sso`
SSO
`ssotkn`
SSO token
`sub`
Stripe subscription
`template`
Template
`user`
User
`uva`
User vault access
`vault`
Vault
`vaultkey`
Vault key
---
## Authorization
Every call to the 1Password Events API must be authorized with a valid [JWT-encoded ](https://datatracker.ietf.org/doc/html/rfc7519) bearer token in the HTTP [request header](/docs/events-api/request-headers/). The token authenticates the client and authorizes it to access specific resources (events), without exposing 1Password account credentials.
## Pass bearer tokens in your API requests
Bearer tokens are passed to the Events API through the `Authorization` header in your request.
### Step 1: Get a bearer token
You'll get a bearer token when you [set up a new Events Reporting integration](/docs/events-api/get-started#step-1-set-up-an-events-reporting-integration), or when you [issue a new token](#issue-a-bearer-token) in an existing integration.
When you generate the token, you'll choose which events the token is scoped to, then save the token in 1Password.
After you set up the integration, you can also [issue or revoke tokens](#manage-bearer-tokens) at any time.
### Step 2: Create an API request
When you make a call to the Events API, you must include the `Authorization` [request header](/docs/events-api/request-headers/) with your bearer token.
The following example uses [curl ](https://curl.se/) on the command line to make a GET request to the [`introspect` endpoint](/docs/events-api/reference#get-apiv2authintrospect). API calls to this endpoint allow you to check that your bearer token is valid and confirm which events it's authorized to access.
1. In your terminal, format your curl request using the following structure:
```shell [{ "badge": 1, "color": "tangerine", "lineNo": 2, "substr": "" }, { "badge": 2, "color": "lagoon", "lineNo": 3, "substr": "" }]
curl --request GET \
--url /api/v2/auth/introspect \
--header 'Authorization: Bearer '
```
2. Replace the {''} placeholder in the endpoint with the [events URL for your 1Password account](/docs/events-api/servers/).
3. Replace {''} in the `Authorization` header with the token for your Events Reporting integration.
- Option 1: Copy the credential field from the bearer token you saved in 1Password, then paste it in the authorization header. For example:
```shell [{ "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjNyaTN0NDR0anZvZmNmbWc0Z2tsNWk2b2FpIiwidHlwIjoiSldUIn0..." }]
--header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjNyaTN0NDR0anZvZmNmbWc0Z2tsNWk2b2FpIiwidHlwIjoiSldUIn0...'
```
The `...` at the end of the bearer token here indicates it's been truncated for the example. You'll need to include the full credential string for your token.
- Option 2: [Use an environment variable to load your API token](/docs/events-api/generic-scripts#usage) to avoid revealing your bearer token in plaintext. You'll need to use double quotes for the authorization header to allow for variable expansion. For example:
```shell [{ "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "${EVENTS_API_TOKEN}" }]
--header "Authorization: Bearer ${EVENTS_API_TOKEN}"
```
### Step 3: Send the API request
Send the API request from the terminal. For example:
```shell [{ "badge": 1, "color": "tangerine", "lineNo": 2, "substr": "https://events.1password.com" }, { "badge": 2, "color": "lagoon", "lineNo": 3, "substr": "${EVENTS_API_TOKEN}" }]
curl --request GET \
--url https://events.1password.com/api/v2/auth/introspect \
--header "Authorization: Bearer ${EVENTS_API_TOKEN}"
```
If you've installed [jq ](https://jqlang.github.io/jq/), you can add `| jq` at the end of your request to pretty-print the JSON response.
If your token is authenticated, the API will return a [`200` response](/docs/events-api/reference#responses) that includes the events (features) scoped to your token. For example:
```json
{
"uuid": "OK41XEGLRTH4YKO5YRTCPNX3IU",
"issued_at": "2025-10-17T16:32:50-03:00",
"features": [
"auditevents",
"itemusages",
"signinattempts"
],
"account_uuid": "M4E2SWNZAZFTRGQGDNS2E5A4MU"
}
```
If you get a `401 Unauthorized` error, make sure your bearer token is in the `Authorization` header and is formatted correctly.
Learn more about [status codes in the Events API](/docs/events-api/status-codes/).
## Manage bearer tokens
After you set up your Events Reporting integration, you can [issue](#issue-a-bearer-token) additional bearer tokens, [revoke](#revoke-a-bearer-token) tokens, and [verify the scope](#verify-the-scope-of-a-bearer-token) of existing tokens.
### Issue a bearer token
To issue a new bearer token for an existing integration:
1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com and select **[Integrations](https://start.1password.com/integrations/active)** in the sidebar.
2. Choose the Events Reporting integration where you want to issue a token and select **Add a token**.
3. Set up a new bearer token:
- **Token Name**: Enter a name for the token.
- **Expires After**: (Optional) Choose when the token will expire: 30 days, 90 days, or 180 days. The default setting is Never.
- **Events to Report**: Choose which events the token can access. The default setting includes all events: sign-in attempts, item usages, and audit events.
4. Select **Issue Token**.
5. On the "Save your token" page, select **Save in 1Password**. Choose the vault where you want to save your token, then select **Save**. Your bearer token will be saved as an API Credential item in 1Password.
If you set a bearer token to expire, you can also edit the item you saved in 1Password if you want to add the token's expiry date.
### Revoke a bearer token
:::caution
Your SIEM will stop ingesting events after a token is revoked. To minimize downtime, issue a replacement token before you revoke one.
:::
To revoke a bearer token:
1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com and select **[Integrations](https://start.1password.com/integrations/active)** in the sidebar.
2. Choose the Events Reporting integration where you want to revoke a token.
3. Select the gear button next to the token you want to revoke, then select **Revoke**.
### Verify the scope of a bearer token
To verify a bearer token's scope, check the integration details on 1Password.com:
1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com and select **[Integrations](https://start.1password.com/integrations/active)** in the sidebar.
2. Choose the Events Reporting integration where you want to verify the scope of a token.
3. Locate your bearer token in the Tokens section and check which events it can access. You will also see when or if the token is set to expire.
Alternatively, you can make a [GET request to the introspection endpoint](/docs/events-api/reference#get-apiv2authintrospect) to verify which events are scoped to the token.
---
## About the Events API beta
The 1Password Events API v3 (version 3) beta is a REST-style HTTP API that follows the [OpenAPI 3.0 ](https://spec.openapis.org/oas/latest.html) specification. All requests are made over HTTPS and return JSON responses.
The beta introduces a [new v3 versioned endpoint](/docs/events-api/beta/reference/get-v3-audit-events):
- `GET /api/v3/auditevents`
This endpoint returns audit events for actions performed by team members in a 1Password account. Each event describes:
- Who performed the action (the actor).
- What was affected (one or more target entities).
- Where and how the action occurred (context about the account, location, client, device, and session).
The beta API can be used alongside the existing Events API. The v1 and v2 endpoints for audit events, item usages, and sign-in attempts remain available.
## Request methods
The beta API currently supports a single HTTP method (GET) to retrieve audit events and uses query parameters for pagination and time filters.
The `/api/v3/auditevents` beta endpoint uses GET with query parameters for pagination and time filters.
:::info
The v1 and v2 API endpoints continue to use POST requests with a cursor object in the request body.
:::
## Servers and URLs
The v3 beta endpoint is currently hosted on the same Events API servers as the production API. Your base URL depends on the [region](https://support.1password.com/regions/) where your 1Password account is hosted:
| 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` |
To call the beta endpoint, append the v3 path to your base URL:
```text
$BASE_URL/api/v3/auditevents
```
All requests must be made over HTTPS.
:::info
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](/docs/events-api/beta/roadmap) to track changes.
:::
## Endpoints
The v3 beta API uses the following endpoint:
- [`GET /api/v3/auditevents`](/docs/events-api/beta/reference/get-v3-audit-events): Retrieve audit events for actions performed by team members within a 1Password account.
Item usage and sign-in attempt events remain available through the existing v1 and v2 endpoints.
## Authorization
All calls to the v3 beta endpoint must be authorized with a valid [JWT-encoded ](https://datatracker.ietf.org/doc/html/rfc7519) bearer token in the [`Authorization` header](#request-headers). The token must be scoped to include audit events.
## Request headers
Requests to the beta endpoint require the `Authorization` header:
```shell
Authorization: Bearer $EVENTS_API_TOKEN.
```
If your bearer token is missing, malformed, or invalid, the API will return a `401 Unauthorized` response.
## Pagination
The beta API uses cursor-based pagination passed in the query string.
### Query parameters
The v3 `auditevents` endpoint accepts the following optional query parameters:
- `page_size`: The maximum number of events to return in a single response.
- `start_time`: The earliest timestamp to include in the result set (inclusive).
- `end_time`: The latest timestamp to include in the result set (inclusive).
- `next_page_token`: An opaque token that identifies the next page of results to retrieve.
:::info
Data collection for the `/api/v3/auditevents` beta endpoint started December 1, 2025. To access event data prior to that date, you'll need to use the [`/api/v2/auditevents` production endpoint](/docs/events-api/reference#post-apiv2auditevents).
:::
### Response metadata
Every `200` successful response includes a `meta` object with pagination metadata:
- `next_page_token`: A token you can pass to the next request to retrieve the next page of results.
- `has_more`: A boolean value that indicates whether additional pages are available (`true` or `false`).
When `has_more` is `true`, you can continue making requests with `next_page_token` until there are no more events, indicated by `"has_more": false`.
### 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 `page_size`, `start_time`, and `end_time` parameters you need. Note that data collection for this endpoint started December 1, 2025.
2. Check the response: Process the `audit_events` and check the `has_more` and `next_page_token` metadata.
3. Subsequent requests: If `has_more` is `true`, call the endpoint again. For example:
```shell
curl --request GET \
--url "https://events.1password.com/api/v3/auditevents?next_page_token=eyJQYWdlU2l6ZSI6NSwiU3RhcnRUaW1lIjoiMjAyNS0xMC0wMVQwMDowMDowMFoiLCJFbmRUaW1lIjoiMjAyNi0wMS0wNlQyMTozMzo0Ny44NDA2MjA3NFoiLCJTZWFyY2hBZnRlciI6MTc2MzA2MjYxMjQ0MCwiVGllQnJlYWtlciI6IkpaUjdaNDNMN1ZGVDVLVE0zRURBRURSRlBRIn0" \
--header "Authorization: Bearer $EVENTS_API_TOKEN"
```
Repeat until `has_more` is `false` and you’ve retrieved all events for the requested interval.
Make sure not to use the `start_time` and `end_time` query parameters with the `next_page_token` query parameter. Doing so will result in a `400` bad request error.
## 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 Unix timestamp (in seconds) that indicates when the current rate limit window will reset.
If you exceed the allowed rate, the API returns a `429 Too Many Requests` response. The `429` response includes the following header:
`Retry-After`: 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.
---
## Events API beta roadmap and changelog
:::caution Beta features are not guaranteed
The purpose of this roadmap is to provide beta testers with information about new or improved features that are available for testing. Beta features and improvements may be added, changed, or removed at any time and are not intended to be used in production. You can use the [beta changelog](#beta-changelog) to track changes.
:::
You can use the beta roadmap to track the phased rollout of new and improved features planned for the Events API. This page will be updated periodically to indicate when:
- A new or improved feature is ready for public beta testing
- A beta feature moves into production
- A planned feature is added, changed, or removed from the roadmap
## Planned features
| Feature area | Plan | Phase/Status | Additional information |
| --- | --- | ---| --- |
| Audit events | Create new v3 endpoint for audit events, based on updated audit logging model. | Public beta | Beta endpoint available for testing: [`GET /api/v3/auditevents`](/docs/events-api/beta/reference/get-v3-audit-events). |
| Audit log | Rename Activity Log to Audit Log and update to use new audit logging model. | Public beta | Learn more about the [beta audit log](https://support.1password.com/audit-log/). |
| Item usages | Add item usage events to the beta. | Coming soon | |
| Sign-in attempts | Add sign-in attempt events to the beta. | Coming soon | |
| 1Password SaaS Manager (formerly Trelica) | Add SaaS Manager events to Events API and audit log. | Coming soon | |
| 1Password Device Trust (Kolide) | Add Device Trust events to Events API and audit log. | Coming soon | |
## Beta changelog
This section includes information about additive and breaking changes made to the v3 Events API throughout the beta, starting from the public beta release.
### Version 3.0.0 (2026-01-13) {#v3.0.0}
Public release of the Events API v3 beta.
- **Specification file**: [1Password Events API specifications (3.0.0)](https://i.1password.com/media/1password-events-reporting/1password-events-api_3.0.0.yaml)
- **Summary**: We've launched the v3 beta of the 1Password Events API. The beta introduces a new audit logging model that provides a more comprehensive view of the actions being performed in a 1Password account.
- **Details**: Key features include:
- A new [v3 audit events beta endpoint](/docs/events-api/beta/reference/get-v3-audit-events): `/api/v3/auditevents`. This endpoint can return structured audit event data starting from December 1, 2025. Audit event data includes information about who performed an action, what was affected, and context about where and how the action occurred.
- A new `GET` HTTP method for audit events.
- Cursor-based pagination with query parameters for `page_size`, `start_time`, `end_time`, and `next_page`.
- A new [beta audit log](https://support.1password.com/audit-log/) to monitor events that happen on your team from your 1Password.com account.
---
## Get started with the 1Password Events API (beta)
# Get started with the 1Password Events API (Beta)
:::info
This content is for testing the v3 audit events beta endpoint. See how to [get started with the production version (v2)](/docs/events-api/get-started/) if you don't want to use the beta.
:::
You can use the 1Password Events beta API to retrieve audit events from your 1Password Business account and send them to your security information and event management (SIEM) system.
The beta API introduces a [new audit events endpoint](/docs/events-api/beta/reference/get-v3-audit-events) (`/api/v3/auditevents`) that uses the HTTP GET method and cursor-based pagination with query parameters. This beta endpoint returns structured audit event data beginning December 1, 2025. The data includes information about the actor, the affected entities, and contextual information about the account, where the session originated, and more for each event.
[Learn more about the Events API v3 beta.](/docs/events-api/beta/about-v3-beta)
## Requirements
Before you get started with the beta API, you’ll need to have:
- [A 1Password Business account.](https://1password.com/pricing/password-manager)
- An [owner](https://support.1password.com/groups/#owners) or [administrator](https://support.1password.com/groups/#administrators) role in your 1Password account.
- A [JWT bearer token (Events API token)](/docs/events-api/authorization#manage-bearer-tokens) that’s authorized to access audit events for your account.
If you already use the Events API with other endpoint versions, you can reuse the same Events Reporting integration and bearer token with the v3 beta endpoint. Make sure your bearer token is scoped for audit events.
## Step 1: Set up an Events Reporting integration
If you haven’t set up Events Reporting yet, [create a new integration](/docs/events-api/get-started#step-1-set-up-an-events-reporting-integration) in your 1Password Business account and issue a bearer token. Save the token in 1Password, then load it into your environment when making API calls.
If you already have Events Reporting set up for your 1Password account, review the integration details to confirm:
- The integration is active.
- Your bearer token is active and scoped to access audit events.
## Step 2: Find your Events API base URL
The `/api/v3/auditevents` beta endpoint currently uses the same Events API servers as the v2 production endpoint.
Choose the base URL that matches the [region](https://support.1password.com/regions/) where your 1Password account is hosted:
| 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` |
You’ll use this base URL together with the v3 `auditevents` path. For example:
```text
https://events.1password.com/api/v3/auditevents
```
## Step 3: Send a test request with curl
You can send a test request with [curl ](https://curl.se/) on the command line to confirm your integration is working.
:::info
The v3 beta endpoint uses a different HTTP method for requests:
- v3 beta endpoint: `GET /api/v3/auditevents`
- v2 production endpoint: `POST /api/v2/auditevents`
:::
### 3.1: Create a curl request
In your terminal, format your request using the following structure:
```shell
curl --request GET \
--url "$BASE_URL/api/v3/auditevents?page_size={events_per_page}&start_time={start_time}&end_time={end_time}" \
--header "Authorization: Bearer $EVENTS_API_TOKEN"
```
Replace the placeholders with your own values:
- `$BASE_URL`: The Events API base URL for your 1Password account. For example: `https://1password.com`.
- `$EVENTS_API_TOKEN`: The bearer token for your Events Reporting integration.
- `{events_per_page}`: (Optional) The maximum number of events to return in a single response. Use a value from `1` to `1000`. If you don’t include the `page_size` parameter, a default of `100` will be used.
- `{start_time}`: (Optional) The date and time for when you want to start retrieving events, in [RFC 3339 format ](https://datatracker.ietf.org/doc/html/rfc3339). For example: `2026-01-01T00:00:00Z`.
- `{end_time}`: (Optional) The date and time for when you want to stop retrieving events, in [RFC 3339 format ](https://datatracker.ietf.org/doc/html/rfc3339). For example: `2026-01-12T23:59:59Z`.
If you omit the `start_time` and `end_time` parameters, the endpoint will return a page of events using the service-defined default time range.
:::info
Data collection for the `/api/v3/auditevents` beta endpoint started December 1, 2025. To access event data prior to that date, you'll need to make a [`POST` request to the `/api/v2/auditevents` production endpoint](/docs/events-api/reference#post-apiv2auditevents).
:::
### 3.2: Send a curl request
The following example sends a GET request to the [`/api/v3/auditevents` endpoint](/docs/events-api/beta/reference/get-v3-audit-events), using the curl command structure from the example above. Adjust the query parameters as needed.
```json
curl --request GET \
--url "$BASE_URL/api/v3/auditevents?page_size=1&start_time=2026-01-01T00:00:00Z&end_time=2026-01-12T23:59:59Z" \
--header "Authorization: Bearer $EVENTS_API_TOKEN"
#code-result
{
"data": {
"audit_events": [
{
"action": "vault.vault-item.update",
"actor": {
"email": "wendy_appleseed@agilebits.com",
"name": "Wendy Appleseed",
"type": "user",
"uuid": "4HCGRGYCTRQFBMGVEGTABYDU2V"
},
"category": "vault",
"context": {
"account": {
"name": "AgileBits",
"uuid": "VZSYVT2LGHTBWBQGUJAIZVRABM"
},
"client": {
"name": "1Password Extension",
"version": "81118003"
},
"device": {
"model": "142.0.7444.23",
"uuid": "katnz37usfc5i67fqekylwmcde"
},
"location": {
"city": "Toronto",
"country": "Canada",
"ip_address": "192.0.2.254",
"latitude": 43.5991,
"longitude": -79.4988,
"region": "Ontario"
},
"origin": "Admin Console",
"os": {
"name": "MacOSX",
"version": "10.15"
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.1 Safari/605.1.15"
},
"session": {
"login_time": "2025-11-13T18:52:10.706588504Z",
"uuid": "X6TARAEE2NGKFLMK5POQBZ4U2Q"
}
},
"targets": [
{
"payload": {
"type": "P",
"uuid": "lc5fqgbrcm4plajd8mwncv2b3u"
},
"type": "vault"
}
],
"timestamp": "2026-01-01T19:01:20.110679321Z",
"uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM"
}
]
},
"meta": {
"has_more": true,
"next_page_token": "eyLMNWdlU2l6ZSI6NSwiU3RhcnRUaW1lIjoiMjAyNS0xMC0wMVQwMDowMDowMFoiLCJFbmRUaW1lIjoiMjAyNi0wMS0wNlQyMTozMzo0Ny44NDA2MjA3NFoiLOPTZWFyY2hBZnRlciI6MTc2MzA2MjYxMjQRSTwiVGllQnJlYWtlciI6IkpaUjdaUVWMN1ZGVDVLVE0zRXYZRURSRlBRIn0"
}
}
```
For better readabilty, you can also provide the query parameters on separate lines using `--data-urlencode` flags.
```shell
curl --request GET \
--url "$BASE_URL/api/v3/auditevents" \
--header "Authorization: Bearer $EVENTS_API_TOKEN" \
--data-urlencode "page_size=1" \
--data-urlencode "start_time=2026-01-01T00:00:00Z" \
--data-urlencode "end_time=2026-01-12T23:59:59Z"
```
### 3.3: Review the response
Review the response to confirm that the `audit_events` array contains the expected event data. If the response body is empty, try adjusting your `start_time` and `end_time` parameters.
If there are more events available than can be returned in a single response, the beta endpoint returns a meta object that includes:
- `next_page_token`: An opaque token you can pass in the next request to retrieve the next page of results.
- `has_more`: A boolean value that indicates whether more pages are available (`true` or `false`).
For example, the response to the curl request above includes the following meta object:
```json
"meta": {
"next_page_token": "eyLMNWdlU2l6ZSI6NSwiU3RhcnRUaW1lIjoiMjAyNS0xMC0wMVQwMDowMDowMFoiLCJFbmRUaW1lIjoiMjAyNi0wMS0wNlQyMTozMzo0Ny44NDA2MjA3NFoiLOPTZWFyY2hBZnRlciI6MTc2MzA2MjYxMjQRSTwiVGllQnJlYWtlciI6IkpaUjdaUVWMN1ZGVDVLVE0zRXYZRURSRlBRIn0",
"has_more": true
}
```
To request the next page of results, use the `next_page_token` value as a query parameter. For example:
```shell
curl --request GET \
--url "$BASE_URL/api/v3/auditevents?next_page_token=eyLMNWdlU2l6ZSI6NSwiU3RhcnRUaW1lIjoiMjAyNS0xMC0wMVQwMDowMDowMFoiLCJFbmRUaW1lIjoiMjAyNi0wMS0wNlQyMTozMzo0Ny44NDA2MjA3NFoiLOPTZWFyY2hBZnRlciI6MTc2MzA2MjYxMjQRSTwiVGllQnJlYWtlciI6IkpaUjdaUVWMN1ZGVDVLVE0zRXYZRURSRlBRIn0" \
--header "Authorization: Bearer $EVENTS_API_TOKEN"
```
You can continue calling the endpoint with each `next_page_token` value that gets returned until `has_more` is `false`.
Make sure not to include the `start_time` or `end_time` parameters in requests that use a `next_page_token`. Doing so will result in a `400` bad request error.
To view HTTP status codes and rate limit in the responses, you can use the `--include` flag in your request. For example:
```shell
curl --include --request GET...
```
## Step 4: Test the beta endpoint
After you’ve confirmed your Events API integration is working, you can test the beta `/api/v3/auditevents` endpoint with your SIEM.
:::caution
The v3 beta endpoint is stable for testing, but it's possible changes could be made during the beta that will break integrations.
We don't recommend the beta for production use, but we do encourage beta testers to use v3 beta endpoint alongside the v2 production version and provide feedback. You can also use the [Events API beta roadmap and changelog](/docs/events-api/beta/roadmap) to track changes.
:::
---
## Get v3 audit events
# Get v3 audit events (Beta)
:::tip
This API reference documents the latest version of the [1Password Events API beta specifications (3.0.0)](https://i.1password.com/media/1password-events-reporting/1password-events-api_3.0.0.yaml). Learn more [about the beta API](/docs/events-api/beta/about-v3-beta).
:::
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 or invites another team member to a shared vault.
## 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](/docs/events-api/authorization/) 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:
- `page_size`: Specify the number of events records to return per page, between 1 and 1000.
- `start_time`: The date and time from which to start retrieving events.
- `end_time`: The date and time to stop retrieving events.
- `next_page_token`: Add a cursor token from a previous response to go to the next page of results.
See the [query parameters schema](#query-parameters-schema) for more details.
### Example requests
Example request with page size and start and end time parameters:
```shell
curl --request GET \
--url https://events.1password.com/api/v3/auditevents?page_size=50&start_time=2026-01-01T00:00:00Z&end_time=2026-01-13T17:30:00Z \
--header 'Authorization: Bearer YOUR_BEARER_TOKEN'
```
Example request that includes a token to return the next page of events:
```shell
curl --request GET \
--url "https://events.1password.com/api/v3/auditevents?next_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), along with pagination metadata that indicates if there are more results (`true` or `false`). If true, the response will include a token you can use to request subsequent pages of events.
If the response is successful but there aren't any events for the parameters you requested, the `audit_events` array will be empty (`[]`).
### HTTP status code
Every request returns an [HTTP status code](/docs/events-api/status-codes) that indicates if the response was successful or there was a problem.
### Response headers
The response may also include one or more of the following `RateLimit` response headers, as defined by the [IETF standards ](https://www.ietf.org/archive/id/draft-polli-ratelimit-headers-02.html#name-header-specifications):
- `Content-Type: application/json`
- `RateLimit-Limit`
- `Ratelimit-Remaining`
- `RateLimit-Reset`
- `Retry-After` (only in responses with a `429 Too Many Requests` error)
You can use the `--include` flag in your request to view the HTTP status code and your remaining rate limit in the response. For example:
```shell
curl --include --request GET...
```
### Example responses
A successful `200` response returns an array of [`AuditEventsResponse` objects](#auditeventsresponse-object) with the following high-level structure:
```json
{
"data": {
"audit_events": [
{
"uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E",
"timestamp": "2025-01-01T00:00:00Z",
"context": { /* Context object */ },
"actor": { /* Actor object */ },
"category": "vault",
"action": "vault.vault-item.update",
"targets": [ /* Entity objects */ ]
}
]
},
"meta": {
"next_page_token": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK",
"has_more": true
}
}
```
Below is an example of a successful response that shows one event (a user edited an item in a shared vault). It includes response headers and metadata with a token to fetch the next page of results.
```json
HTTP/2 200
content-type: application/json
ratelimit-limit: 600
ratelimit-remaining: 599
ratelimit-reset: 1767735927
date: Tue, 13 Jan 2026 17:30:52 GMT
{
"data": {
"audit_events": [
{
"action": "vault.vault-item.update",
"actor": {
"email": "wendy_appleseed@agilebits.com",
"name": "Wendy Appleseed",
"type": "user",
"uuid": "4HCGRGYCTRQFBMGVEGTABYDU2V"
},
"category": "vault",
"context": {
"account": {
"name": "AgileBits",
"uuid": "VZSYVT2LGHTBWBQGUJAIZVRABM"
},
"client": {
"name": "1Password Extension",
"version": "81118003"
},
"device": {
"model": "142.0.7444.23",
"uuid": "katnz37usfc5i67fqekylwmcde"
},
"location": {
"city": "Toronto",
"country": "Canada",
"ip_address": "192.0.2.254",
"latitude": 43.5991,
"longitude": -79.4988,
"region": "Ontario"
},
"origin": "Admin Console",
"os": {
"name": "MacOSX",
"version": "15.7.1"
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.1 Safari/605.1.15"
},
"session": {
"login_time": "2025-11-13T18:52:10.706588504Z",
"uuid": "X6TARAEE2NGKFLMK5POQBZ4U2Q"
}
},
"targets": [
{
"payload": {
"type": "P",
"uuid": "lc5fqgbrcm4plajd8mwncv2b3u"
},
"type": "vault"
}
],
"timestamp": "2026-01-01T19:01:20.110679321Z",
"uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM"
}
]
},
"meta": {
"has_more": true,
"next_page_token": "eyLMNWdlU2l6ZSI6NSwiU3RhcnRUaW1lIjoiMjAyNS0xMC0wMVQwMDowMDowMFoiLCJFbmRUaW1lIjoiMjAyNi0wMS0wNlQyMTozMzo0Ny44NDA2MjA3NFoiLOPTZWFyY2hBZnRlciI6MTc2MzA2MjYxMjQRSTwiVGllQnJlYWtlciI6IkpaUjdaUVWMN1ZGVDVLVE0zRXYZRURSRlBRIn0"
}
}
```
Example response headers when the rate limit of 600 requests per minute has been exceeded:
```json
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 {#query-parameters-schema}
Name
Type
Required
Description
`page_size`
integer
No
Maximum number of events records to return per page, from 1 to 1000. If the `page_size` parameter isn't include, the default of 100 will be used.
`next_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 `next_page_token`. Doing so will result in a `400` bad request error.
`start_time`
string (date-time)
No
The earliest timestamp (inclusive) from which to retrieve events. Invalid if `next_page_token` is specified. Uses the RFC 3339 standard .
`end_time`
string (date-time)
No
The latest timestamp (inclusive) for which to retrieve events. Invalid if `next_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
`data`
object
Yes
Container for the audit event data.
`data.audit_events`
array
Yes
Array of [`AuditEvent` objects](#auditevent-object).
`meta`
object
Yes
Pagination metadata for the response that can be used in subsequent requests.
`meta.next_page_token`
string
No
Opaque token used to retrieve the next page of results. Should be included in subsequent requests until `has_more` is false.
`meta.has_more`
boolean
Yes
Indicates if additional pages of results are available for retrieval (`true`) or not (`false`).
#### AuditEventsResponse: AuditEvent object {#auditevent-object}
Field
Type
Required
Description
`uuid`
string
Yes
Unique identifier for the audit event.
`timestamp`
string (date-time)
Yes
The date and time when the event occurred. Uses the RFC 3339 standard .
`context`
object
Yes
A [`Context` object](#context-object) containing information about how the event was initiated.
`actor`
object
Yes
An [`Actor` object](#actor-object) describing who initiated the event.
`category`
string
Yes
High-level category of the event (for example, `report`).
`action`
string
Yes
Specific action taken (for example, `report.view`).
`targets`
array
Yes
Array of [`Entity` objects](#entity-object) that describe what was affected.
#### AuditEventsResponse: Account object {#account-object}
Field
Type
Required
Description
`uuid`
string
Yes
UUID 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, `1password.com`).
#### AuditEventsResponse: Actor object {#actor-object}
Field
Type
Required
Description
`type`
string
Yes
The type of actor (for example, `user`).
`uuid`
string
Yes
UUID 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](#account-object) describing a related account, if any.
#### AuditEventsResponse: Client object {#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 {#context-object}
Field
Type
Required
Description
`account`
object
Yes
A [`ContextAccount` object](#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](#session-object) describing the session in which the event occurred.
`location`
object
Yes
A [`Location` object](#location-object) describing where the event originated.
`device`
object
No
A [`Device` object](#device-object) describing the device used to initiate the event.
`client`
object
No
A [`Client` object](#client-object) describing the 1Password client used (app or integration).
`os`
object
No
An [`OS` object](#os-object) describing the operating system.
#### AuditEventsResponse: ContextAccount object {#contextaccount-object}
Field
Type
Required
Description
`uuid`
string
Yes
UUID of the account.
`name`
string
Yes
Name of the account.
#### AuditEventsResponse: Device object {#device-object}
Field
Type
Required
Description
`uuid`
string
Yes
UUID of the device.
`model`
string
Yes
Model of the device.
#### AuditEventsResponse: Entity object {#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 {#location-object}
Field
Type
Required
Description
`ip_address`
string
Yes
IP address from which the event originated.
`country`
string
No
Country associated with the IP address.
`region`
string
No
Region associated with the IP address.
`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 {#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.
`userAgent`
string
No
Information about the operating system, such as software identification and environment details.
#### AuditEventsResponse: Session object {#session-object}
Field
Type
Required
Description
`uuid`
string
Yes
UUID of the session.
`login_time`
string (date-time)
Yes
Time when the session was created.
### ErrorResponse object
Field
Type
Required
Description
`Error`
object
No
An [`Error` object](#error-object) containing the error message.
#### ErrorResponse: Error object {#error-object}
Field
Type
Required
Description
`Message`
string
No
An error message.
---
## 1Password Events API changelog
This changelog tracks notable changes to the 1Password Events API and provides information about when changes were made and what changed.
## Summary of changes
| Version | Date | Type | Description | Details |
|---------|------|------|-------------|---------|
| 1.4.1 | September 2025 | Improvement | Added an account UUID property to the introspect response object. | [View details](#september-2025) |
| 1.4.0 | November 2024 | New feature | Added V2 endpoints for sign-in attempts and item usage with external user and MSP support. (*Breaking change* *) | [View details](#november-2024) |
| 1.3.0 | September 2024 | New feature | Added V2 audit events endpoint with external user and MSP support. (*Breaking change* *) | [View details](#september-2024) |
| 1.2.0 | November 2023 | New feature | Added passkey credential support to audit events. | [View details](#november-2023) |
| 1.2.0 | August 2023 | Improvement | Enhanced user details in audit event responses. | [View details](#august-2023) |
| 1.2.0 | November 2022 | New feature | Added audit events endpoint and reporting capabilities. | [View details](#november-2022) |
| 1.2.0 | March 2022 | Improvement | Added geolocation info and SSO actions. | [View details](#march-2022) |
| 1.1.0 | September 2021 | Improvement | Added internal server error handling. | [View details](#september-2021) |
| 1.1.0 | August 2021 | New feature | Added V2 introspection endpoint. (*Breaking change* *) | [View details](#august-2021) |
| 1.0.0 | July 2021 | Initial release | Initial public release of the 1Password Events API. | [View details](#july-2021) |
* Breaking changes are backwards-incompatible changes that require an upgrade to use. When breaking changes are released, we'll continue to support previous versions of the API and you can choose when to upgrade your API version.
## September 2025 (version 1.4.1) {#september-2025}
Added a new `account_UUID` property to the introspect endpoint (/api/v2/auth/introspect).
You can now confirm the account a bearer token was issued from. This is particularly relevant to managed service providers (MSPs) that manage multiple accounts.
## November 2024 (version 1.4.0 ) {#november-2024}
Added new V2 endpoints with external user and MSP functionality:
- POST /api/v2/signinattempts
- POST /api/v2/itemusages
Changes include:
- New SignInAttemptV2 schema:
- Added `account_uuid` field
- Added `federated` sign-in type
- Uses enhanced UserV2 schema
- New ItemUsageV2 schema:
- Added `account_uuid` field
- Uses enhanced UserV2 schema
- New SignInAttemptUserTypes enum for user type classification
### Breaking changes
V2 endpoints introduce new required fields and response structures. If upgrading from V1:
- Response schemas include new required fields
- User objects now include type classification
- New enums added for MSP functionality
### Migration impact
V1 endpoints continue to be supported. Migration to V2 endpoints is only required if you're an MSP provider and you need to access MSP-related event data for your account or the accounts of your managed companies.
New integrations can use V2 endpoints regardless of MSP needs.
## September 2024 (version 1.3.0) {#september-2024}
Added new V2 audit events endpoint with MSP support:
- POST /api/v2/auditevents
Changes include:
- New AuditEventV2 schema:
- Added `actor_type` field
- Added `actor_account_uuid` field
- Added `account_uuid` field
- Added AuditEventActorTypes enum
- Added new actions:
- `expire`
- `launchi`
- `unlink`
- Added `mngdacc` object type for managed accounts
## November 2023 (version 1.2.0) {#november-2023}
- Added "cred" object type for passkey authentication
- Fixed latitude field name in Location schema
## August 2023 (version 1.2.0) {#august-2023}
Enhanced AuditEvent schema with detailed user information:
- Added `actor_details`
- Added `object_details`
- Added `aux_details`
## November 2022 (version 1.2.0) {#november-2022}
- Added audit events endpoint (/api/v1/auditevents)
- Added new schemas:
- AuditEvent
- AuditEventItems
- AuditEventActions
- AuditEventObjectTypes
- Session
## March 2022 (version 1.2.0) {#march-2022}
- Added Location object to sign-in attempts and item usage events:
- `country`
- `region`
- `city`
- `longitude`
- `latitude`
- Added new item usage actions:
- `select-sso-provider`
- `enter-item-edit-mode`
## September 2021 (version 1.1.0) {#september-2021}
- Added 500 Internal Server Error response to all endpoints
## August 2021 (version 1.1.0) {#august-2021}
Added V2 introspection endpoint:
- New introspection endpoint (/api/v2/auth/introspect)
- V1 endpoint marked as deprecated
- Added IntrospectionV2 schema with consistent naming
## July 2021 (Version 1.0.0) {#july-2021}
Initial [public release of the 1Password Events API](https://blog.1password.com/introducing-events-api/), including:
- Introspection endpoint
- JWT authentication
- Item usage endpoint
- Sign-in attempts endpoint
- Cursor-based pagination
---
## Endpoints
## Endpoint structure
Each API endpoint starts with a [base URL](/docs/events-api/servers/), followed by the resource or operation path:
```text [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "base_url" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "/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`](/docs/events-api/reference#get-apiv2authintrospect), [`auditevents`](/docs/events-api/reference#post-apiv2auditevents), [`itemusages`](/docs/events-api/reference#post-apiv2itemusages), or [`signinattempts`](/docs/events-api/reference#post-apiv2signinattempts).
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" [{ "badge": 1, "color": "sunbeam", "lineNo": 1, "substr": "https://events.ent.1password.com" }, { "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "/api/v2/auditevents" }]
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](/docs/events-api/changelog/) to learn more about the changes in the V2 endpoints and previous versions of the API.
---
## 1Password Events API generic scripts
:::info
If you're new to Events Reporting, [learn how to get started with 1Password Events API](/docs/events-api/get-started/).
:::
To help you get started with the 1Password Events API we've put together a [repository of example scripts](https://github.com/1Password/events-api-generic) across several languages, including [JavaScript](https://github.com/1Password/events-api-generic/blob/main/eventsapi.js), [Python](https://github.com/1Password/events-api-generic/blob/main/eventsapi.py), [Ruby](https://github.com/1Password/events-api-generic/blob/main/eventsapi.rb), [Go](https://github.com/1Password/events-api-generic/blob/main/eventsapi.go), and [PHP](https://github.com/1Password/events-api-generic/blob/main/eventsapi.php). The scripts will print up to 20 sign-in attempts and item usage events from the last 24 hours.
## Requirements
Before implementing any of the examples, or your own scripts, you'll need to generate a bearer token and store it in your 1Password account.
To get a bearer token, you can:
- [Set up a new Events Reporting integration.](/docs/events-api/get-started#step-1-set-up-an-events-reporting-integration)
- [Issue a new token](/docs/events-api/authorization#issue-a-bearer-token) in an existing integration.
- [Generate a token with 1Password CLI.](/docs/cli/reference/management-commands/events-api#events-api-create)
## Usage
All scripts use the `EVENTS_API_TOKEN` environment variable to load your API token.
We recommend setting `EVENTS_API_TOKEN` to a [secret reference](/docs/cli/secret-reference-syntax/) that points to where your bearer token is saved in 1Password, to avoid revealing the token in plaintext. Then you can use [`op run`](/docs/cli/reference/commands/run/) with [1Password CLI](/docs/cli/) to securely provision the token at runtime.
[Learn more about securely loading secrets from the environment.](/docs/cli/secrets-environment-variables/)
For example, to set the [`EVENTS_API_TOKEN` environment variable](/docs/cli/secrets-environment-variables#use-environment-env-files) with an environment file, then use [`op run`](/docs/cli/reference/commands/run/) to run the PHP `eventsapi.php` script with the variable provisioned:
```shell title="events.env"
EVENTS_API_TOKEN="op://Vault/Item/token"
```
```
op run --env-file="./events.env" -- php eventsapi.php
```
To export the [`EVENTS_API_TOKEN` environment variable](/docs/cli/secrets-environment-variables#export-environment-variables), then use [`op run`](/docs/cli/reference/commands/run/) to run the Go `eventsapi.go` script with the variable provisioned:
**bash, sh, zsh, fish:**
```shell
EVENTS_API_TOKEN="op://Vault/Item/token" op run -- go run eventsapi.go
```
**Powershell:**
1. Export the necessary environment variables:
```powershell
$Env:EVENTS_API_TOKEN = "op://Vault/Item/token"
```
2. Run op run -- with your command for starting the app:
```powershell
op run -- go run eventsapi.go
```
## Learn more
- [Get started with the 1Password Events API](/docs/events-api/get-started/)
- [Issue or revoke bearer tokens for the Events API](/docs/events-api/authorization#manage-bearer-tokens)
- [About 1Password Events Reporting security](https://support.1password.com/events-reporting-security/)
---
## Get started with the 1Password Events API
You can use the 1Password Events API to set up an integration between your 1Password Business account and your security information and event management (SIEM) system.
## Requirements
Before you get started, you'll need to [sign up for a 1Password Business account](https://1password.com/pricing/password-manager).
If you already have a business account, you'll need to be an [owner](https://support.1password.com/1password-glossary#owner) or [administrator](https://support.1password.com/1password-glossary#administrator) to set up an Events Reporting integration.
## Step 1: Set up an Events Reporting integration
You can set up an Events Reporting integration in your 1Password Business account:
1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com.
2. Select [**Integrations**](https://start.1password.com/integrations/directory) in the sidebar. If you've set up other integrations in your account, you'll also need to select **Directory** on the Integrations page.
3. In the Events Reporting section, choose your SIEM from the list. If your SIEM isn't listed, select **Other**.
4. Enter a name for the integration, then select **Add Integration**.
5. Set up a bearer token:
- **Token Name**: Enter a name for the token.
- **Expires After**: (Optional) Choose when the token will expire: 30 days, 90 days, or 180 days. The default setting is Never.
- **Events to Report**: Choose which events the token can access. The default scope includes all events: sign-in attempts, item usages, and audit events.
6. Select **Issue Token**.
7. On the "Save your token" page, select **Save in 1Password**. Choose the vault where you want to save your token, then select **Save**. Your bearer token will be saved as an API Credential item in 1Password.
8. Select **View Integration Details**.
You can issue or revoke bearer tokens for your Events Reporting integration at any time. Learn more about [how to manage bearer tokens](/docs/events-api/authorization#manage-bearer-tokens).
## Step 2: Test the integration
Before you connect your 1Password account with your SIEM, you can send a test request to the Events API using [curl ](https://curl.se/) on the command line. Specify the [endpoint](/docs/events-api/endpoints/) along with any required [request headers](/docs/events-api/request-headers/) and data.
### 1. Create a curl request
In your terminal, format your curl request using the following structure:
```shell [{ "badge": 1, "color": "intrepidblue", "lineNo": 1, "substr": "" }, { "badge": 2, "color": "sunbeam", "lineNo": 2, "substr": "" }, { "badge": 3, "color": "lagoon", "lineNo": 2, "substr": "" }, { "badge": 4, "color": "dahlia", "lineNo": 3, "substr": "" }, { "badge": 5, "color": "bitsblue", "lineNo": 6, "substr": "" }, { "badge": 6, "color": "tangerine", "lineNo": 7, "substr": "" }, { "badge": 6, "color": "tangerine", "lineNo": 8, "substr": "" }]
curl --request \
--url / \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"limit": ,
"start_time": "",
"end_time": ""
}'
```
The `Content-Type` header and the `--data` flag with [pagination](/docs/events-api/pagination/) content are only used in `POST` requests to the Events API.
Replace the highlighted content with your preferred values:
{''} The [HTTP request method](/docs/events-api/request-methods/) you want to use for your request. For example: `POST`.
{''} The [base URL](/docs/events-api/servers/) of the server used for events in your 1Password account. For example: `https://events.1password.com`.
{''} The path of the [endpoint](/docs/events-api/endpoints/) you want to use. For example: `/api/v2/signinattempts`.
{''}: The bearer token you generated in [step 1](#step-1-set-up-an-events-reporting-integration). You can use one of the following options:
- Option 1: Copy the credential field from the bearer token you saved in 1Password, then paste it in the authorization header. For example:
```shell [{ "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjNyaTN0NDR0anZvZmNmbWc0Z2tsNWk2b2FpIiwidHlwIjoiSldUIn0..." }]
--header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjNyaTN0NDR0anZvZmNmbWc0Z2tsNWk2b2FpIiwidHlwIjoiSldUIn0...'
```
The `...` at the end of the bearer token here indicates it's been truncated for the example. You'll need to include the full credential string for your token.
- Option 2: [Use an environment variable to load your API token](/docs/events-api/generic-scripts#usage) to avoid revealing your bearer token in plaintext. You'll need to use double quotes for the authorization header to allow for variable expansion. For example:
```shell [{ "badge": 2, "color": "lagoon", "lineNo": 1, "substr": "${EVENTS_API_TOKEN}" }]
--header "Authorization: Bearer ${EVENTS_API_TOKEN}"
```
{''} The optional [pagination limit](/docs/events-api/pagination/) for the maximum number of event records you want returned per page. (POST requests only.) Choose a value from `1` to `1000`.
{''} The optional [RFC 3339-formatted ](https://datatracker.ietf.org/doc/html/rfc3339) date and time (UTC) for when you want to start and stop retrieving events. (POST requests only.) For example: `2025-10-31T09:00:00Z`.
The pagination limit, start time, and end time data is all optional. If you don't want to include them in your POST request, use an empty request body for the `--data` flag:
```shell
--data '{}'
```
### 2. Send a curl request
Send your formatted curl request from the terminal.
The following example sends a POST request to the [`signinattempts` endpoint](/docs/events-api/reference#post-apiv2signinattempts), using the curl command structure from the example above.
```json
curl --request POST \
--url https://events.1password.com/api/v2/signinattempts \
--header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6Imt6aXJ4NHQ0Mm1laDVwbmFhcm4yYjZucXN1IiwidHlwIjoiSldUIn0...' \
--header 'Content-Type: application/json' \
--data '{
"limit": 1,
"start_time": "2025-10-31T09:00:00Z",
"end_time": "2025-10-31T17:00:00Z"
}'
#code-result
{
"cursor": "ZX8DAQETRWxhc3RpY3NlYXJjaEN1cnNvcgH_gAABBQEFTGltaXQBBAABCVN0YXJ0VGltZQH_ggABB0VuZFRpbWUB_4IAAQtTZWFyY2hBZnRlcgEEAAEKVGllQnJlYWtlcgEMAAAACv-BBQEC_4QAAABL_4ABAgEPAQAAAA7gjFYQAAAAAP7UAQ8BAAAADuCSBYgAAAAA_tQB-gM0JEhDqgEaQlRYUFUzM1ZOTkJLVERST0lGRUVUQkZQNlUA",
"has_more": true,
"items": [
{
"uuid": "BTXPU33VNNBKTDROIFEETBFP6U",
"session_uuid": "DU72R2RHZRHUTOYHMG44EDG4UI",
"timestamp": "2025-10-31T13:45:49.203617068Z",
"country": "CA",
"category": "success",
"type": "credentials_ok",
"details": null,
"client": {
"app_name": "1Password for Mac",
"app_version": "81118011",
"platform_name": "Wendy’s MacBook Pro",
"platform_version": "MacBookPro18,2",
"os_name": "MacOSX",
"os_version": "15.7.1",
"ip_address": "192.0.2.254"
},
"location": {
"country": "CA",
"region": "Ontario",
"city": "Toronto",
"latitude": 43.5991,
"longitude": -79.4988
},
"target_user": {
"uuid": "ETWZJTQCSRFPVOX74KERGHPBTU",
"name": "Wendy Appleseed",
"email": "wendy_appleseed@agilebits.com",
"type": "user"
},
"account_uuid": "4XHKKHXODJANPD6ZTBAXK4IM7E"
}
]
}
```
### 3. Review the response
Review the response that was returned to check that the request was successful.
The example request above shows a successful `200` response, with JSON objects detailing the sign-in attempt event(s) and a cursor for continued calling of the API. See the [response schema for the `signinattempts` endpoint](/docs/events-api/reference#responses-3) for more information.
If the request was successful but your 1Password account didn't contain any events within the parameters of your request, the response will still return an object with a [cursor string](/docs/events-api/pagination#cursor). For example:
```json
{
"cursor": "ZX8DAQETRWxhc3RpY3NlYXJjaEN1cnNvcgH_gAABBQEFTGltaXQBBAABCVN0YXJ0VGltZQH_ggABB0VuZFRpbWUB_4IAAQtTZWFyY2hBZnRlcgEEAAEKVGllQnJlYWtlcgEMAAAACv-BBQEC_4QAAAAn_4ABAgEPAQAAAA7gfNhwAAAAAP__AQ8BAAAADuB84vwAAAAA__8A",
"has_more": false,
"items": []
}
```
If you made a call to a different endpoint, check the [Events API reference](/docs/events-api/reference/) for the appropriate response object schema.
If you see an error, learn more about [HTTP status codes and recommended actions for error messages](/docs/events-api/status-codes).
## Step 3: Connect your 1Password account to your SIEM
### Use a pre-built connector
Many SIEMs already support connecting with 1Password. To use a pre-built connector, [check if your SIEM is in the list of supported applications or services](https://support.1password.com/events-reporting#step-2-connect-your-1password-account-to-your-siem). If it is, you can follow the provided link for documentation on how to connect your 1Password account.
If your SIEM isn't listed, you can also check the documentation for that service for any information they might have about connecting to a 1Password account.
### Build your own integration
If your SIEM doesn't have a pre-built connector, you can build your own client to send your 1Password account activity to your SIEM. Use the [Events API reference](/docs/events-api/reference/) and documentation to learn more about how the API works.
To help you get started, you can refer to the [example scripts in our GitHub repository ](https://github.com/1Password/events-api-generic/) for JavaScript, Python, Ruby, Go, and PHP. Learn more about [how to use the example scripts](/docs/events-api/generic-scripts/).
## Learn more
- [1Password Events API reference](/docs/events-api/reference/)
- [About the 1Password Events API](/docs/events-api/introduction/)
- [1Password Events API generic scripts](/docs/events-api/generic-scripts/)
- [GitHub repository of example scripts ](https://github.com/1Password/events-api-generic/)
---
## About the 1Password Events API
The 1Password Events API is a REST-style API that follows the [OpenAPI 3.0 Specifications](https://spec.openapis.org/oas/latest.html). All communication between clients and servers are over HTTPS.
You can use your preferred language and tools for testing and implementing the Events API. The examples in the [API reference](/docs/events-api/reference/) use [curl ](https://curl.se/) 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 audit log in your 1Password account](https://support.1password.com/activity-log/).
## Requirements
Before you can use the 1Password Events API, you'll need to:
- [Sign up for 1Password Business](https://1password.com/pricing/password-manager).
- [Set up an Events Reporting integration](/docs/events-api/get-started) in your 1Password account.
- [Create a bearer token](/docs/events-api/authorization#step-1-get-a-bearer-token) and select the event features it can access.
---
## Item usage actions
You can use the [1Password Events API](/docs/events-api/reference/) to send your 1Password account activity to your security information and event management (SIEM) system, including item usage.
[ItemUsage objects](/docs/events-api/reference#post-apiv2itemusages) contain actions, which describe how an item was used.
:::warning[caution]
Actions are only captured from client apps using 1Password 8.4.0 or later.
Item usage activity is only sent when client apps sync to the 1Password server. Not all item usage triggers a sync, so there may be delays before actions are received.
:::
## Item usage action values
Possible values for `action` include:
- `enter-item-edit-mode`
- `export`
- `fill`
- `other`
- `reveal`
- `secure-copy`
- `select-sso-provider`
- `server-create`
- `server-fetch`
- `server-update`
- `share`
The behaviors that trigger each type of action are grouped below by 1Password client type.
### enter-item-edit-mode
Client
Behavior
1Password apps
Add an item to Favorites.Edit an item. Usage is recorded upon selecting Edit, whether or not the item is modified.
### export
Client
Behavior
1Password apps
Download a file.Export 1Password account data as a 1PUX or CSV file. Usage is recorded for every exported item.
### fill
Client
Behavior
1Password apps
Fill an item by selecting:
"Open and fill"
"Type in window" (Windows only)
1Password in the browser
Fill an item by selecting:
Autofill
Auto-Type (Windows only)
Open & Fill
An item from the inline menu in a form field
### other
Item usage actions are only captured from devices using 1Password 8.4.0 or later. The `other` value indicates the action was performed using an earlier version of 1Password and is unknown.
Client
Behavior
1Password apps
Action is unknown.
### reveal
Client
Behavior
1Password apps
Preview a file.Reveal a password.Show a password in large type.
1Password in the browser
Reveal a password.Show a password in large type.
### secure-copy
Client
Behavior
1Password apps
Copy an item field.Copy an item's password history.
1Password in the browser
Copy an item field.Copy an item in JSON format.
### select-sso-provider
Client
Behavior
1Password in the browser
Sign in to a site using a sign-in provider.
### server-create
The `server` prefix indicates that the action occurred on the server rather than in the client app.
Client
Behavior
1Password apps
Duplicate an item.Move an item.
1Password.com
Create an item.Duplicate an item.
1Password CLI
Create an item.
1Password Connect server
Create an item.
### server-fetch
The `server` prefix indicates that the action occurred on the server rather than the client app. `server-fetch` is a special kind of action type that isn't used by most clients. It's only used when the client reporting the usage is a web server, like 1Password Connect server.
Client
Behavior
1Password apps
Download a file.Preview a file.
1Password.com
Open an item.
1Password CLI
Open an item.
1Password Connect server
Get all of an item's files.Get the contents of a file.Get the details of a file.Get the details of an item.
### server-update
The `server` prefix indicates that the action occurred on the server rather than the client app.
Client
Behavior
1Password apps
Add an item to Favorites.Archive an item.Delete an item.Edit an item.Move an item.Restore an item.
1Password in the browser
Add an item to Favorites.
1Password.com
Add an item to Favorites.Archive an item.Delete an item.Edit an item.Restore an item.
1Password CLI
Archive an item.Delete an item.Edit an item.
1Password Connect server
Delete an item.Edit an item.Replace an item.
### share
Client
Behavior
1Password apps
Copy an item in JSON format.Duplicate an item.Move an item.Share a link to an item.
1Password.com
Share a link to an item.
## Learn more
- [Get started with 1Password Events Reporting](https://support.1password.com/events-reporting/)
- [1Password Events API reference](/docs/events-api/reference/)
- [Get started with 1Password Events Reporting and Elastic](https://support.1password.com/events-reporting-elastic/)
- [Get started with 1Password Events Reporting and Splunk](https://support.1password.com/events-reporting-splunk/)
- [1Password command-line tool: Full documentation](/docs/cli/reference/)
---
## 1Password Events API
The 1Password Events API allows you to retrieve information about activity in your 1Password Business account and send it to your security information and event management (SIEM) system. With the Events API, you can keep track of:
- Actions team members take in the account, such as changes to vaults, groups, users, and more.
- How and when items in shared vaults are used, like when an item is viewed, copied, or edited.
- Attempts to sign in to the 1Password account, including when and where a user signed in to the account, and detailed information about failed sign in attempts.
## Quick start
To create an Events Reporting integration to connect your 1Password Business account with your SIEM, [start here](/docs/events-api/get-started).
After you set up the integration in your 1Password account, read more [about the 1Password Events API](/docs/events-api/introduction) and look at some [example scripts](/docs/events-api/generic-scripts).
## Reference documentation
- Read the full [1Password Events API reference](/docs/events-api/reference/).
- Learn about [audit events](/docs/events-api/audit-events/).
- Learn about [item usage actions](/docs/events-api/item-usage-actions).
- Track [version changes](/docs/events-api/changelog/).
---
## 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](#reset-cursor) and a [cursor](#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:
**Example reset cursor request:**
```json
{
"limit": 100,
"start_time": "2023-03-15T16:32:50-03:00",
"end_time": "2023-03-15T17:32:50-03:00"
}
```
**ResetCursor object schema:**
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
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.
**Example cursor:**
```json
{
"cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK"
}
```
**Cursor object schema:**
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](http://support.1password.com/events-reporting-splunk/) and [Elastic](http://support.1password.com/events-reporting-elastic/) will 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
```
---
## 1Password Events API reference
:::tip
This API reference documents the latest version of the [1Password Events API specifications (1.4.1)](https://i.1password.com/media/1password-events-reporting/1password-events-api_1.4.1.yaml). Learn more about [API versions](/docs/events-api/endpoints#endpoint-versions).
:::
## GET /api/v2/auth/introspect
```
base_url/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. It also returns the UUID of the account where the token was issued.
### Parameters
No parameters.
### Requests
Use the full URL of the `introspect` endpoint with your [bearer token](/docs/events-api/authorization/) and the required [request headers](/docs/events-api/request-headers/). A GET request doesn't include a body, so the content type header isn't needed.
For example:
```shell
curl --request GET \
--url base_url/api/v2/auth/introspect \
--header 'Authorization: Bearer YOUR_BEARER_TOKEN'
```
### 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.
**Example introspection response:**
```json
{
"uuid": "OK41XEGLRTH4YKO5YRTCPNX3IU",
"issued_at": "2023-03-05T16:32:50-03:00",
"features": [
"auditevents",
"itemusages",
"signinattempts"
],
"account_uuid": "M4E2SWNZAZFTRGQGDNS2E5A4MU"
}
```
**IntrospectionV2 object schema:**
Name
Type
Description
`uuid`
string
The UUID of the Events Reporting integration.
`issued_at`
string
The date and time the token was issued. Uses the RFC 3339 standard.
`features`
array of strings
A list of event features the integration has access to. Possible values are one or more of:
`auditevents`
`itemusages`
`signinattempts`
`account_uuid`
string
The UUID of the account where the bearer token was issued.
## POST /api/v2/auditevents
```
base_url/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](/docs/events-api/audit-events/).
This endpoint requires a [bearer token](/docs/events-api/authorization/) with the `auditevents` feature. You can make an [introspection call](#get-apiv2authintrospect) 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](/docs/events-api/authorization/) and the required [request headers](/docs/events-api/request-headers/). You must include a [ResetCursor](/docs/events-api/pagination#reset-cursor) object or the [cursor](/docs/events-api/pagination#cursor) from a previous response in the request body.
**Example audit events request with a reset cursor:**
```shell
curl --request POST \
--url base_url/api/v2/auditevents \
--header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"limit": 100,
"start_time": "2023-03-15T16:32:50-03:00"
}'
```
**Example audit events request with a continuing cursor:**
```shell
curl --request POST \
--url base_url/api/v2/auditevents \
--header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK"
}'
```
### 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
**Example audit event response:**
```json
{
"cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK",
"has_more": true,
"items": [
{
"uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E",
"timestamp": "2023-03-15T16:33:50-03:00",
"actor_uuid": "4HCGRGYCTRQFBMGVEGTABYDU2V",
"actor_details": {
"uuid:": "4HCGRGYCTRQFBMGVEGTABYDU2V",
"name": "Jeff Shiner",
"email": "jeff_shiner@agilebits.com"
},
"action": "join",
"object_type": "gm",
"object_uuid": "pf8soyakgngrphytsyjed4ae3u",
"aux_id": 9277034,
"aux_uuid": "K6VFYDCJKHGGDI7QFAXX65LCDY",
"aux_details": {
"uuid": "K6VFYDCJKHGGDI7QFAXX65LCDY",
"name": "Wendy Appleseed",
"email": "wendy_appleseed@agilebits.com"
},
"aux_info": "R",
"session": {
"uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM",
"login_time": "2023-03-15T16:33:50-03:00",
"device_uuid": "lc5fqgbrcm4plajd8mwncv2b3u",
"ip": "192.0.2.254"
},
"location": {
"country": "Canada",
"region": "Ontario",
"city": "Toronto",
"latitude": 43.5991,
"longitude": -79.4988
}
}
]
}
```
**AuditEventV2 object schemas:**
#### AuditEventItemsV2 object schema
Name
Type
Description
`cursor`
string
Cursor to return more event data or to continue polling.
`has_more`
boolean
Whether there's more data to be returned using the cursor. If the value is `true`, there may be more events. If the value is `false`, there are no more events.
`items`
array
An array of AuditEventV2 objects.
##### AuditEventV2 object schema
Name
Type
Description
`uuid`
string
The UUID of the action event.
`timestamp`
string
The date and time when the action was performed. Uses the RFC 3339 standard.
`actor_uuid`
string
The UUID of the user who performed the action.
`actor_details`
object
A user object.
`actor_type`
string
The type of user who performed the action (internal or external). Possible values are:
`user`
`external_user` (MSP accounts only)
`actor_account_uuid`
string
The UUID of the account the user belongs to.
`account_uuid`
string
The UUID of the account where the action was performed.
`action`
string
The type of action that was performed. Possible values are:
`"activate"`
`"addgsso"`
`"begin"`
`"beginr"`
`"cancel"`
`"cancelr"`
`"changeks"`
`"changeks"`
`"changela"`
`"changemp"`
`"changenm"`
`"changesk"`
`"chngasso"`
`"chngdsso"`
`"chngpsso"`
`"complete"`
`"completr"`
`"convert"`
`"create"`
`"dealldev"`
`"delete"`
`"delgsso"`
`"delshare"`
`"deolddev"`
`"detchild"`
`"disblduo"`
`"disblmfa"`
`"disblsso"`
`"dlgsess"`
`"dvrfydmn"`
`"enblduo"`
`"enblmfa"`
`"enblsso"`
`"expire"`
`"export"`
`"grant"`
`"hide"`
`"join"`
`"launchi"`
`"leave"`
`"musercom"`
`"muserdec"`
`"patch"`
`"propose"`
`"provsn"`
`"prsndall"`
`"purge"`
`"rdmchild"`
`"reactive"`
`"reauth"`
`"replace"`
`"replace"`
`"resendts"`
`"revoke"`
`"role"`
`"sdvcsso"`
`"sendpkg"`
`"sendts"`
`"share"`
`"ssotknv"`
`"suspend"`
`"tdvcsso"`
`"trename"`
`"trevoke"`
`"trvlaway"`
`"trvlback"`
`"tverify"`
`"uisas"`
`"unhide"`
`"unknown"`
`"unlink"`
`"updatduo"`
`"update"`
`"updatea"`
`"updatfw"`
`"updatmfa"`
`"upguest"`
`"uvrfydmn"`
`"verify"`
`"view"`
`"vrfydmn"`
Learn about audit event actions.
`object_type`
string
The type of object the action was performed on. Possible values are:
`"account"`
`"card"`
`"cred"`
`"device"`
`"dlgdsess"`
`"ec"`
`"famchild"`
`"file"`
`"gm"`
`"group"`
`"gva"`
`"invite"`
`"item"`
`"itemhist"`
`"items"`
`"miguser"`
`"mngdacc"`
`"pm"`
`"report"`
`"sa"`
`"satoken"`
`"slackapp"`
`"sso"`
`"ssotkn"`
`"sub"`
`"template"`
`"user"`
`"uva"`
`"vault"`
`"vaultkey"`
Learn about audit event objects.
`object_uuid`
string
The unique identifier for the object the action was performed on.
`object_details`
object
An object details object. Returned if the object is a user.
`aux_id`
integer
The identifier for someone or something that provides additional information about the activity. For example, the ID of a device that a user adds or removes from an account.
`aux_uuid`
string
The unique identifier for someone or something that provides additional information about the activity. For example, the UUID of a team member who joins or leaves a group in an account.
`aux_details`
object
An aux details object. Returned if the aux details relate to a user.
`aux_info`
string
Additional information about the activity.
`session`
object
A session object.
`location`
object
A location object that contains details about the geolocation of the client based on the client's IP address at the time the event was performed.
###### UserV2 object schema
Name
Type
Description
`uuid`
string
The UUID of the user who performed the action.
`name`
string
The name of the user who performed the action.
`email`
string
The email address of the user who performed the action.
`user_type`(MSP accounts only)
string
The type of user who performed the action (internal or external). Possible values are:
`user_account_uuid`(MSP accounts only)
string
The UUID of the user's account.
###### Object details object schema
Name
Type
Description
`uuid`
string
The UUID of the user who is the object of the action.
`name`
string
The name of the user who is the object of the action.
`email`
string
The email address of the user who is the object of the action.
###### Aux details object schema
Name
Type
Description
`uuid`
string
The UUID of the user related to the additional information about the activity. For example, the user who was added to or removed from the account or vault or whom created or deleted the device.
`name`
string
The name of the user related to the additional information about the activity.
`email`
string
The email address of the user related to the additional information about the activity.
###### Session object schema
Name
Type
Description
`uuid`
string
The UUID of the session.
`login_time`
string
The date and time the client signed in and started the session. Uses the RFC 3339 standard.
`device_uuid`
string
The UUID of the device signed in to the session.
`ip`
string
The IP address used for the session.
###### Location object schema
Name
Type
Description
`country`
string
The country where the action was performed.
`region`
string
The region where the action was performed.
`city`
string
The city where the action was performed.
`longitude`
number
A coordinate that specifies the longitudinal location for where the action was performed.
`latitude`
number
A coordinate that specifies the latitudinal location for where the action was performed.
## POST /api/v2/itemusages
```
base_url/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](/docs/events-api/item-usage-actions/).
This endpoint requires a [bearer token](/docs/events-api/authorization/) with the `itemusages` feature. You can make an [introspection call](#get-apiv2authintrospect) 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](/docs/events-api/authorization/) and the required [request headers](/docs/events-api/request-headers/). You must include a [ResetCursor](/docs/events-api/pagination#reset-cursor) object or the [cursor](/docs/events-api/pagination#cursor) from a previous response in the request body.
**Example item usage request with a reset cursor:**
```shell
curl --request POST \
--url base_url/api/v2/itemusages \
--header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"limit": 100,
"start_time": "2023-03-15T16:32:50-03:00"
}'
```
**Example item usage request with a continuing cursor:**
```shell
curl --request POST \
--url base_url/api/v2/itemusages \
--header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK"
}'
```
### 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.
**Example item usage response:**
```json
{
"cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK",
"has_more": true,
"items": [
{
"uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E",
"timestamp": "2023-03-15T16:33:50-03:00",
"used_version": 0,
"vault_uuid": "VZSYVT2LGHTBWBQGUJAIZVRABM",
"item_uuid": "SDGD3I4AJYO6RMHRK8DYVNFIDZ",
"user": {
"uuid": "4HCGRGYCTRQFBMGVEGTABYDU2V",
"name": "Wendy Appleseed",
"email": "wendy_appleseed@agilebits.com"
},
"client": {
"app_name": "1Password Browser",
"app_version": "20240",
"platform_name": "Chrome",
"platform_version": "string",
"os_name": "MacOSX",
"os_version": "13.2",
"ip_address": "192.0.2.254"
},
"location": {
"country": "Canada",
"region": "Ontario",
"city": "Toronto",
"latitude": 43.5991,
"longitude": -79.4988
},
"action": "secure-copy"
}
]
}
```
**ItemUsageV2 object schemas:**
#### ItemUsageItemsV2 object schema
Name
Type
Description
`items`
array
An array of ItemUsageV2 objects.
`cursor`
string
Cursor to return more event data or to continue polling.
`has_more`
boolean
Whether there's more data to be returned using the cursor. If the value is `true`, there may be more events. If the value is `false`, there are no more events.
##### ItemUsageV2 object schema
Name
Type
Description
`uuid`
string
The UUID of the event.
`timestamp`
string
The date and time of the event. RFC 3339 standard.
`used_version`
integer
The version of the item that was accessed.
`vault_uuid`
string
The UUID of the vault the item is in.
`item_uuid`
string
The UUID of the item that was accessed.
`action`
string
Details about how the item was used. Actions are only captured from client apps using 1Password 8.4.0 or later. Possible values are:
`"enter-item-edit-mode"`
`"export"`
`"fill"`
`"other"`
`"reveal"`
`"secure-copy"`
`"select-sso-provider"`
`"server-create"`
`"server-fetch"`
`"server-update"`
`"share"`
Learn about item usage actions.
`user`
object
A user object.
`client`
object
A client object.
`location`
object
A location object that contains details about the geolocation of the client based on the client's IP address at the time the event was performed.
`account_uuid`(MSP accounts only)
string
The UUID of the account where the action was performed.
###### UserV2 object schema
Name
Type
Description
`uuid`
string
The UUID of the user that accessed the item or attempted to sign in to the account.
`name`
string
The name of the user, hydrated at the time the event was generated.
`email`
string
The email address of the user, hydrated at the time the event was generated.
`user_type`(MSP accounts only)
string
The type of user who performed the action (internal or external). Possible values are:
`user_account_uuid`(MSP accounts only)
string
The UUID of the user's account.
###### Client object schema
Name
Type
Description
`app_name`
string
The name of the 1Password app the item was accessed from.
`app_version`
string
The version number of the app.
`platform_name`
string
The name of the platform the item was accessed from.
`platform_version`
string
The version of the browser or computer where 1Password is installed or the CPU of the machine where the 1Password command-line tool is installed.
`os_name`
string
The name of the operating system the item was accessed from.
`os_version`
string
The version of the operating system the item was accessed from.
`ip_address`
string
The IP address the item was accessed from.
###### Location object schema {#location-object-schema-1}
Name
Type
Description
`country`
string
The country where the item was accessed.
`region`
string
The region where the item was accessed.
`city`
string
The city where the item was accessed.
`longitude`
number
A coordinate that specifies the longitudinal location for where the item was accessed.
`latitude`
number
A coordinate that specifies the latitudinal location for where the item was accessed.
## POST /api/v2/signinattempts
```
base_url/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](/docs/events-api/authorization/) with the `signinattempts` feature. You can make an [introspection call](#get-apiv2authintrospect) 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](/docs/events-api/authorization/) and the required [request headers](/docs/events-api/request-headers/). You must include a [ResetCursor](/docs/events-api/pagination#reset-cursor) object or the [cursor](/docs/events-api/pagination#cursor) from a previous response in the request body.
**Example request with a reset cursor:**
```shell
curl --request POST \
--url base_url/api/v2/signinattempts \
--header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"limit": 100,
"start_time": "2023-03-15T16:32:50-03:00"
}'
```
**Example request with a continuing cursor:**
```shell
curl --request POST \
--url base_url/api/v2/signinattempts \
--header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK"
}'
```
### 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.
**Example sign-in attempt response:**
```json
{
"cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK",
"has_more": true,
"items": [
{
"uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E",
"session_uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM",
"timestamp": "2023-03-15T16:32:50-03:00",
"category": "firewall_failed",
"type": "continent_blocked",
"country": "France",
"details": {
"value": "Europe"
},
"target_user": {
"uuid": "IR7VJHJ36JHINBFAD7V2T5MP3E",
"name": "Wendy Appleseed",
"email": "wendy_appleseed@agilebits.com"
},
"client": {
"app_name": "1Password Browser",
"app_version": "20240",
"platform_name": "Chrome",
"platform_version": "string",
"os_name": "MacOSX",
"os_version": "13.2",
"ip_address": "192.0.2.254"
},
"location": {
"country": "Canada",
"region": "Ontario",
"city": "Toronto",
"latitude": 43.5991,
"longitude": -79.4988
}
}
]
}
```
**SignInAttemptsV2 object schemas:**
#### SignInAttemptItemsV2 object schema
Name
Type
Description
`items`
array
An array of SignInAttemptsV2 objects.
`cursor`
string
Cursor to return more event data or to continue polling.
`has_more`
boolean
Whether there's more data to be returned using the cursor. If the value is `true`, there may be more events. If the value is `false`, there are no more events.
##### SignInAttemptsV2 object schema
Name
Type
Description
`uuid`
string
The UUID of the event.
`session_uuid`
string
The UUID of the session that created the event.
`timestamp`
string
The date and time of the sign-in attempt. Uses the RFC 3339 standard.
`category`
string
The category of the sign-in attempt. Possible values are:
`"success"`
`"credentials_failed"`
`"mfa_failed"`
`"sso_failed"`
`"modern_version_failed"`
`"firewall_failed"`
`"firewall_reported_success"`
`type`
string
Details about the sign-in attempt. Possible values are:
`"all_blocked"`
`"anonymous_blocked"`
`"code_bad"`
`"code_disabled"`
`"code_timeout"`
`"continent_blocked"`
`"country_blocked"`
`"credentials_ok"`
`"duo_bad"`
`"duo_disabled"`
`"duo_native_bad"`
`"duo_timeout"`
`"federated"`
`"ip_blocked"`
`"mfa_missing"`
`"mfa_ok"`
`"modern_version_missing"`
`"modern_version_old"`
`"non_sso_user"`
`"password_secret_bad"`
`"platform_secret_bad"`
`"platform_secret_disabled"`
`"platform_secret_proxy"`
`"service_account_sso_denied"`
`"sso_user_mismatch"`
`"totp_bad"`
`"totp_disabled"`
`"totp_timeout"`
`"u2f_bad"`
`"u2f_disabled"`
`"u2f_timeout"`
`country`
string
The country code of the event. Uses the ISO 3166 standard.
`details`
object
A details object that contains additional information about the sign-in attempt.
`target_user`
object
A user object.
`client`
object
A client object.
`location`
object
A location object that contains details about the geolocation of the client based on the client's IP address at the time the event was performed.
`account_uuid`(MSP accounts only)
string
The UUID of the account where the action was performed.
###### Details object schema
Name
Type
Description
`value`
string
The additional information about the sign-in attempt, such as any firewall rules that prevent a user from signing in. For example, in the event of a sign-in attempt blocked by firewall rules, the value is the country, continent, or IP address of the sign-in attempt.
###### UserV2 object schema {#userv2-object-schema-2}
Name
Type
Description
`uuid`
string
The UUID of the user that accessed the item or attempted to sign in to the account.
`name`
string
The name of the user, hydrated at the time the event was generated.
`email`
string
The email address of the user, hydrated at the time the event was generated.
`user_type`(MSP accounts only)
string
The type of user who performed the action (internal or external). Possible values are:
`user_account_uuid`(MSP accounts only)
string
The UUID of the user's account.
###### Client object schema {#client-object-schema-1}
Name
Type
Description
`app_name`
string
The name of the 1Password app the item was accessed from.
`app_version`
string
The version number of the app.
`platform_name`
string
The name of the platform the item was accessed from.
`platform_version`
string
The version of the browser or computer where 1Password is installed or the CPU of the machine where the 1Password command-line tool is installed.
`os_name`
string
The name of the operating system the item was accessed from.
`os_version`
string
The version of the operating system the item was accessed from.
`ip_address`
string
The IP address the item was accessed from.
###### Location object schema {#location-object-schema-2}
Name
Type
Description
`country`
string
The country where the sign-in attempt was made.
`region`
string
The region where the sign-in attempt was made.
`city`
string
The city where the sign-in attempt was made.
`longitude`
number
A coordinate that specifies the longitudinal location where the sign-in attempt was made.
`latitude`
number
A coordinate that specifies the latitudinal location where the sign-in attempt was made.
## ErrorResponse object
**Example error response:**
```json
{
status: 401,
message: "Unauthorized access"
}
```
**ErrorResponse object schema:**
Name
Type
Description
`status`
integer
The HTTP status code.
`message`
string
A message detailing the error.
---
## 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](/docs/events-api/authorization/) 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
```
---
## Request methods
The Events API accepts the following standard HTTP request methods:
- GET requests to the [`introspect`](/docs/events-api/reference#get-apiv2authintrospect) 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`](/docs/events-api/reference#post-apiv2auditevents), [`itemusages`](/docs/events-api/reference#post-apiv2itemusages ), and [`signinattempts`](/docs/events-api/reference#post-apiv2signinattempts) 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 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` |
---
## 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](/docs/events-api/reference/) and documentation [about the API](/docs/events-api/introduction/) 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](/docs/events-api/request-headers/), and make sure your bearer token is valid and scoped to access the requested resource. [Learn more about authorizing API requests.](/docs/events-api/authorization/) |
| `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.](/docs/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](https://status.1password.com/) to verify the Events API service is operational, or [contact 1Password Support](https://support.1password.com/contact/) for help. |