Authentication & Authorization

Authentication & Authorization

The SaaS Research Agent supports two authentication methods: API Key and OAuth 2.0. These are alternatives — clients can authenticate with either method.

API Key Authentication

All production requests require an API key in the x-api-key header:

curl -X POST https://agent.stactize.com/ \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "x-user-id: user-12345" \
  -H "Content-Type: application/json" \
  -d '{...}'

API Key Management

Key Lifecycle

1. Obtain: Request from andre.witte@1nebula.com
2. Activate: Configure in your application
3. Monitor: Track usage and quota
4. Rotate: Replace every 90 days
5. Revoke: Immediately if compromised

Key Restrictions

Your API key can be restricted by:
– API: Limited to saas-research-api only
– IP Address: Specific IPs or CIDR ranges
– HTTP Referrer: Specific domains (for web apps)

Recommendation: Apply IP restrictions for production keys

Error Codes

OAuth 2.0 Authentication (Gemini Enterprise)

In addition to API key authentication, the agent supports OAuth 2.0 Authorization Code Grant Flow for integration with Google’s Gemini Enterprise platform via Google Cloud Marketplace.

How It Works

When a customer purchases the SaaS Research Agent on Google Cloud Marketplace and adds it to their Gemini Enterprise instance, the following happens automatically:

1. Gemini Enterprise reads the agent card and discovers the DCR extension
2. Gemini Enterprise calls the DCR endpoint with a Google-signed JWT
3. The agent validates the JWT and returns OAuth 2.0 client credentials
4. Gemini Enterprise uses these credentials for the OAuth 2.0 Authorization Code flow
5. On each agent invocation, Gemini Enterprise passes an access token and a signed software_statement

Agent Card Security Configuration

The agent card declares both authentication methods (OAuth 2.0 and API key) as alternatives:

{
  "security_schemes": {
    "google_oauth": {
      "type": "oauth2",
      "description": "Google OAuth 2.0 Authorization Code flow for Gemini Enterprise",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
          "tokenUrl": "https://oauth2.googleapis.com/token",
          "scopes": {
            "profile": "User profile information",
            "email": "User email address"
          }
        }
      }
    },
    "api_key": {
      "type": "apiKey",
      "description": "API key authentication via x-api-key header",
      "name": "x-api-key",
      "in": "header"
    }
  },
  "security": [
    {"google_oauth": ["profile", "email"]},
    {"api_key": []}
  ]
}

The security array uses logical OR: clients can authenticate with either OAuth 2.0 or an API key.

Authentication Methods Summary