Authentication Setup

When you connect an Agent Engine (Vertex AI) agent to TraptureIQ, you need to choose how TraptureIQ authenticates to your Google Cloud project. We offer three options so you can pick the one that fits your organization's security policies.

---

Choosing the Right Method

Method	Best for	What you share with TraptureIQ	Setup time
Authorize with Impersonation	Most organizations	Your service account email (not a secret)	~5 min
Authorize TraptureIQ Principal	Teams that prefer simplest setup	Nothing — you grant access in your Google Cloud project	~2 min
Upload SA Key	Organizations with cross-domain permission restrictions	An encrypted copy of your service account key	~5 min

Recommended

Authorize with Impersonation is our recommended method. No credentials are exchanged, you retain full control, and you can revoke access instantly. This is the same approach used by Datadog, Terraform Cloud, and other leading SaaS platforms.

---

Option 1: Authorize with Impersonation

How it works: You create a service account in your Google Cloud project and allow TraptureIQ to temporarily act as that account. TraptureIQ never receives a key — it requests short-lived tokens from Google Cloud each time it needs access.

What TraptureIQ stores: Only your service account's email address — no credentials are exchanged.

Setup Steps

Step 1 — Create a service account in your project

Go to your Google Cloud Console > IAM & Admin > Service Accounts > Create Service Account.

• Name: traptureiq-access (or any name you prefer)
• Description: "Used by TraptureIQ to access Agent Engine"

Step 2 — Grant it the roles your agent needs

On the same page, grant the service account these roles:

Role	Purpose
Vertex AI User	Invoke your Agent Engine
Logs Viewer (optional)	Let TraptureIQ pull logs for the Logs page
Cloud Trace User (optional)	Let TraptureIQ pull traces for the Traces page

Step 3 — Authorize TraptureIQ to impersonate this account

Still in the Service Accounts page, click on your new service account > Permissions tab > Grant Access.

• New principal: Enter TraptureIQ's service account email (shown in the registration form)
• Role: Service Account Token Creator
• Click Save

Step 4 — Enter the email in TraptureIQ

Back in the agent registration form, paste your service account email into the "Your Service Account Email" field and click Test Connection.

Revoking Access

To disconnect TraptureIQ at any time, go to your service account's Permissions tab and remove the Service Account Token Creator role from TraptureIQ's principal. Access is revoked immediately — no keys to rotate or delete.

---

Option 2: Authorize TraptureIQ Principal

How it works: You add TraptureIQ's service account directly to your Google Cloud project's permissions and grant it the roles it needs. This is the simplest setup — no service account creation required on your side.

What TraptureIQ stores: Nothing — access is managed entirely through Google Cloud permissions.

Setup Steps

Step 1 — Get TraptureIQ's service account email

The email is shown in the registration form when you select this option (e.g., the service account email shown in the registration form).

Step 2 — Grant access in your project

Go to your Google Cloud Console > IAM > Grant Access.

• New principal: TraptureIQ's service account email
• Roles: Vertex AI User, and optionally Logs Viewer and Cloud Trace User
• Click Save

Step 3 — Test Connection

Back in TraptureIQ, click Test Connection to verify access.

Revoking Access

Remove TraptureIQ's service account from your project's permissions page. Access is revoked immediately.

When to choose this method

• You want the fastest possible setup
• Your organization doesn't have restrictions on adding external service accounts to your Google Cloud project
• You prefer a single-step permissions grant without creating additional service accounts

---

Option 3: Upload SA Key

How it works: You create a service account in your Google Cloud project, download its JSON key file, and upload it to TraptureIQ. The key is stored securely and used to authenticate on your behalf.

What TraptureIQ stores: An encrypted copy of your service account key, stored securely.

Setup Steps

Step 1 — Create a service account in your project

Go to your Google Cloud Console > IAM & Admin > Service Accounts > Create Service Account.

• Name: traptureiq-access
• Grant it the roles: Vertex AI User (and optionally Logs Viewer, Cloud Trace User)

Step 2 — Create and download a JSON key

Click on the service account > Keys tab > Add Key > Create new key > JSON.

A .json file will download to your computer.

Step 3 — Upload the key in TraptureIQ

In the agent registration form, click the upload area and select the JSON file. TraptureIQ will validate the file and auto-detect your GCP project ID.

Step 4 — Test Connection

Click Test Connection to verify everything works.

Revoking Access

You can revoke access in two ways:

1. Immediate: Go to your service account's Keys tab in Google Cloud Console and delete the key. TraptureIQ will lose access within the hour.
2. Permanent: Delete the service account entirely.

When to choose this method

• Your organization has cross-domain permission policies that prevent granting roles to external service accounts
• Your security team requires that all access is through organization-owned credentials
• You prefer file-based credential exchange over permissions grants

Key rotation

We recommend rotating your service account keys every 90 days. To rotate:

1. Create a new key in Google Cloud Console
2. Upload the new key in TraptureIQ (edit the agent)
3. Delete the old key in Google Cloud Console

---

Comparison at a Glance

	Impersonation	Direct Access	Key Upload
Credentials leave your project?	No	No	Yes (encrypted)
Can revoke instantly?	Yes	Yes	Yes (delete key)
Key rotation needed?	No	No	Every 90 days
Works with cross-domain permissions?	Yes	No	Yes
Setup complexity	Medium	Low	Medium
Recommended for production?	Yes	Yes	Yes

---

Need Help?

If you're unsure which method to choose, start with Authorize with Impersonation — it works for most organizations and offers the best security posture. If your security team has specific requirements, reach out to us at traptureiq@techtrapture.com.