Authorization

Every call to the 1Password Events API must be authorized with a valid JWT-encoded bearer token in the HTTP request header. 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, or when you issue a new 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 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 with your bearer token.

The following example uses curl on the command line to make a GET request to the introspect endpoint. 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:

2. Replace the <base_url> placeholder in the endpoint with the events URL for your 1Password account.

3. Replace <YOUR_BEARER_TOKEN> 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:

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

Step 3: Send the API request

Send the API request from the terminal. For example:

If you've installed 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 that includes the events (features) scoped to your token. For example:

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.

Manage bearer tokens

After you set up your Events Reporting integration, you can issue additional bearer tokens, revoke tokens, and verify the scope of existing tokens.

Issue a bearer token

To issue a new bearer token for an existing integration:

1. Sign in to your account on 1Password.com and select Integrations 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 to your account on 1Password.com and select Integrations 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 to your account on 1Password.com and select Integrations 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 to verify which events are scoped to the token.