1Password Events API reference

tip

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

GET /api/v2/auth/introspect

A GET call to this endpoint returns a list of events (features) a bearer token is authorized to access, including one or more of: audit events, item usage, and sign-in attempts. 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 and the required request headers. A GET request doesn't include a body, so the content type header isn't needed.

For example:

Responses

200

Returns an Introspection object

400

Bad request

401

Unauthorized access

500

Internal server error

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

Example introspection response

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

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

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

Parameters

No parameters.

Requests

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

Example audit events request with a reset cursor

Example audit events request with a continuing cursor

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

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 external_user
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

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

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

Parameters

No parameters.

Requests

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

Example item usage request with a reset cursor

Example item usage request with a continuing cursor

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

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 external_user
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

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

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

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

Parameters

No parameters.

Requests

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

Example request with a reset cursor

Example request with a continuing cursor

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

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

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 external_user
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

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

ErrorResponse object schema

Name	Type	Description
status	integer	The HTTP status code.
message	string	A message detailing the error.