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.


If you want to view the API in another tool, you can download the API specification file:

 1password-events-api.yaml


Requests

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 a start time, end time (optional), and limit in the request body. The 1Password Events API apps for Splunk and Elastic will store the cursor position for future requests.

For continued calling of the API, include a cursor object in the request body to start at the indicated position to avoid missing any data.

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/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.

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.

Responses

200
Returns a SignInAttempt object
400
Bad request
401
Unauthorized access

Response object models

ResetCursor object

{
  "limit": 100,
  "start_time": "2021-03-01T16:32:50-03:00"
  "end_time": "2021-03-01T16:32:50-03:00"
}
Name Type Description
limit number How many events should be returned in a single request.

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

start_time string The date and time to start retrieving events. Uses the RFC 3339 standard .
end_time string The date and time to stop retrieving events. Uses the RFC 3339 standard . Optional.

Introspection object

{
  "UUID": "string",
  "IssuedAt": "2020-06-11T16:32:50-03:00",
  "Features": [
    "itemusages",
    "signinattempts"
  ]
}
Name Type Description
UUID string The UUID of the integration.
IssuedAt string The date and time of the introspection. Uses the RFC 3339 standard .
Features string A list of features the integration has access to.

ItemUsageItems object

{
  "items": [
  ],
  "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK",
  "has_more": true
}
Name Type Description
items array An array of ItemUsage objects.
cursor string Cursor to return more event data or to continue calling.
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.

ItemUsage object

{
  "uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E",
  "timestamp": "2020-06-11T16:32:50-03:00",
  "used_version": 0,
  "vault_uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E",
  "item_uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E",
  "user": {
    "uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E",
    "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"
  }
}
Name Type Description
uuid string The UUID of the event.
timestamp string The date and time of the event. Uses the 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.
user object A User object.
client object A Client object.

User object

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.

Client object

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.

SignInAttemptItems object

{
  "items": [
  ],
  "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK",
  "has_more": true
}
Name Type Description
items array An array of SignInAttempt objects.
cursor string Cursor to return more event data or to continue calling.
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.

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"
  }
}
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"
  • "modern_version_failed"
  • "firewall_failed"
  • "firewall_reported_success"
type string Details 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"
country string The country code of the event. Uses the ISO 3166 standard .
details object Additional 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_user object A User object.
client object A Client object.

ErrorResponse object

{
  status: 401,
  message: "Unauthorized access"
}
Name Type Description
status integer The HTTP status code.
message string A message detailing the error.
Published: