Teams and Businesses

1Password Events API reference

Learn how to build your own Events Reporting client using the 1Password Events REST API.

Tip

If you’re new to Events Reporting, learn how to get started with 1Password Events Reporting.

You can use the 1Password Events REST API to send your 1Password account activity to your security information and event management (SIEM) system.


To view the API in another tool, download the API specification file:

 1password-events-api.yaml


Requests

Servers

Start each request to the Events API with the URL of the server that hosts your 1Password account.

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

Request headers

Each request to the Events API is authenticated with a bearer token. Provide it and specify the content type:

Authorization: Bearer <bearer_token>
Content-type: application/json

Request body

To begin ingesting data, make an authenticated request to the Events API.

For the first request, include a ResetCursor object with optional start time, end time, and limit parameters in the request body. For example:

{
  "limit": 100,
  "start_time": "2021-03-01T16:32:50-03:00",
  "end_time": "2021-03-01T16:32:50-03:00"
}

For continued calling of the API, include the cursor from the previous response in the request body instead of the ResetCursor object. This will start the request at the indicated position to avoid missing any data. For example:

{
  "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK"
}

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

Rate limits

Rate limits for the Events API are set to 600 requests per minute and up to 30,000 requests per hour. Requests that exceed those limits will return an error.

Responses

429
Too many requests

Introspection

GET /api/v2/auth/introspect

Returns information about the provided bearer token.

Parameters

No parameters.

Responses

200
Returns an Introspection object
400
Bad request
401
Unauthorized access

Item usage

POST /api/v1/itemusages

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 it was accessed, and the vault where the item is stored.

Parameters

No parameters.

Request Body

You must include a ResetCursor object, or the cursor from a previous response, in the Request Body for this call.

Responses

200
Returns an ItemUsage object
400
Bad request
401
Unauthorized access

Sign-in attempts

POST /api/v1/signinattempts

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.

Parameters

No parameters.

Request Body

You must include a ResetCursor object, or the cursor from a previous response, in the Request Body for this call.

Responses

200
Returns a SignInAttempt object
400
Bad request
401
Unauthorized access

Request object models

ResetCursor object

{
  "limit": 100,
  "start_time": "2021-03-01T16:32:50-03:00",
  "end_time": "2021-03-01T16:32:50-03:00"
}
NameTypeDescription
limitnumberHow many events should be returned in a single request. Optional. If not specified, limit will default to 100.

Specify a limit from 1 to 1000. To return additional events, use the cursor position for subsequent requests.

start_timestringThe date and time to start retrieving events. Uses the RFC 3339 standard . Optional. 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_timestringThe date and time to stop retrieving events. Uses the RFC 3339 standard . Optional.

Response object models

Introspection object

{
  "uuid": "string",
  "issued_at": "2020-06-11T16:32:50-03:00",
  "features": [
    "itemusages",
    "signinattempts"
  ]
}
NameTypeDescription
uuidstringThe UUID of the integration.
issued_atstringThe date and time of the introspection. Uses the RFC 3339 standard .
featuresstringA list of features the integration has access to.

ItemUsageItems object

{
  "items": [
  ],
  "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK",
  "has_more": true
}
NameTypeDescription
itemsarrayAn array of ItemUsage objects.
cursorstringCursor to return more event data or to continue calling.
has_morebooleanWhether 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.

ItemUsage object

{
  "uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E",
  "timestamp": "2020-06-11T16:32: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 Extension",
    "app_version": "20127",
    "platform_name": "Chrome",
    "platform_version": "string",
    "os_name": "MacOSX",
    "os_version": "10.15.6",
    "ip": "13.227.95.22"
  },
"action": "secure-copy"
}
NameTypeDescription
uuidstringThe UUID of the event.
timestampstringThe date and time of the event. Uses the RFC 3339 standard .
used_versionintegerThe version of the item that was accessed.
vault_uuidstringThe UUID of the vault the item is in.
item_uuidstringThe UUID of the item that was accessed.
userobjectA User object.
clientobjectA Client object.
actionstringDetails about how the item was used. Actions are only captured from client apps using 1Password 8.4.0 or later. Learn about item usage actions.

User object

NameTypeDescription
uuidstringThe UUID of the user that accessed the item or attempted to sign in to the account.
namestringThe name of the user, hydrated at the time the event was generated.
emailstringThe email address of the user, hydrated at the time the event was generated.

Client object

NameTypeDescription
app_namestringThe name of the 1Password app the item was accessed from.
app_versionstringThe version number of the app.
platform_namestringThe name of the platform the item was accessed from.
platform_versionstringThe 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_namestringThe name of the operating system the item was accessed from.
os_versionstringThe version of the operating system the item was accessed from.
ip_addressstringThe IP address the item was accessed from.

SignInAttemptItems object

{
  "items": [
  ],
  "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK",
  "has_more": true
}
NameTypeDescription
itemsarrayAn array of SignInAttempt objects.
cursorstringCursor to return more event data or to continue calling.
has_morebooleanWhether 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.

SignInAttempt object

{
  "uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E",
  "session_uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM",
  "timestamp": "2021-03-01T16: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 Extension",
    "app_version": "20127",
    "platform_name": "Chrome",
    "platform_version": "string",
    "os_name": "MacOSX",
    "os_version": "10.15.6",
    "ip": "13.227.95.22"
  }
}
NameTypeDescription
uuidstringThe UUID of the event.
session_uuidstringThe UUID of the session that created the event.
timestampstringThe date and time of the sign-in attempt. Uses the RFC 3339 standard .
categorystringThe category of the sign-in attempt. Possible values are:
  • "success"
  • "credentials_failed"
  • "mfa_failed"
  • "modern_version_failed"
  • "firewall_failed"
  • "firewall_reported_success"
typestringDetails about the sign-in attempt. Possible values are:
  • "credentials_ok"
  • "mfa_ok"
  • "password_secret_bad"
  • "mfa_missing"
  • "totp_disabled"
  • "totp_bad"
  • "totp_timeout"
  • "totp_bad"
  • "u2f_disabled"
  • "u2f_bad"
  • "u2f_timeout"
  • "duo_disabled"
  • "duo_bad"
  • "duo_timeout"
  • "duo_native_bad"
  • "platform_secret_disabled"
  • "platform_secret_bad"
  • "platform_secret_proxy"
  • "code_disabled"
  • "ip_blocked"
  • "continent_blocked"
  • "country_blocked"
  • "anonymous_blocked"
  • "all_blocked"
  • "modern_version_missing"
  • "modern_version_old"
countrystringThe country code of the event. Uses the ISO 3166 standard .
detailsobjectAdditional information about the sign-in attempt, such as any firewall rules that prevent a user from signing in.

For a sign-in attempt blocked by firewall rules, the value is the country, continent, or IP address of the sign-in attempt.

target_userobjectA User object.
clientobjectA Client object.

ErrorResponse object

{
  status: 401,
  message: "Unauthorized access"
}
NameTypeDescription
statusintegerThe HTTP status code.
messagestringA message detailing the error.

Still need help?

If this article didn't answer your question, contact 1Password Support.

Published: