Getting Started

Quick Start Guide

Quick Start Guide

Get up and running with GovernanceAI in just 5 minutes. We’ll walk you through creating an organization, generating an API key, and making your first guardrail evaluation.

Prerequisites

  • An active GovernanceAI account (SaaS or On-Premise)
  • A terminal with cURL, Python, or Node.js installed
  • 5 minutes of your time

Step 1: Log In & Access Dashboard (1 min)

For SaaS:

  • Visit app.governanceai.com
  • Click Sign In
  • Enter your credentials
  • You’ll land on your organization dashboard

For On-Premise:

  • Visit your instance URL (e.g., https://governanceai.your-domain.com)
  • Log in with your credentials

Step 2: Generate Your First API Key (1 min)

  • Click your avatar (top right) → Settings
  • Navigate to API Keys
  • Click Create New API Key
  • Fill in:
    • Name: My First Key
    • Environment: Production
    • Scope: Select runtime:execute (for making guardrail calls)
  • Click Generate

⚠️ Copy the API key immediately - You won’t see it again!

gak_prod_1234567890abcdefghijklmnopqr

Save it to your environment:

$export GOVERNANCEAI_API_KEY="gak_prod_1234567890abcdefghijklmnopqr"

Step 3: Get Your Organization ID (1 min)

  • Stay in Settings page
  • Look for Organization Details section
  • Copy your Organization ID (looks like org_123abc...)
$export GOVERNANCEAI_ORG_ID="org_123abc..."

Step 4: Make Your First API Call (1 min)

Choose your preferred language:

Option A: cURL

$curl -X POST https://api.governanceai.com/v1/guardrails/evaluate \
>  -H "Authorization: Bearer $GOVERNANCEAI_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "messages": [
>      {
>        "role": "user",
>        "content": "What is the capital of France?"
>      }
>    ],
>    "context": {
>      "org_id": "'$GOVERNANCEAI_ORG_ID'",
>      "user_id": "user_demo",
>      "session_id": "session_123"
>    }
>  }'

Option B: Python

1import requests
2import os
3
4api_key = os.getenv('GOVERNANCEAI_API_KEY')
5org_id = os.getenv('GOVERNANCEAI_ORG_ID')
6
7response = requests.post(
8    'https://api.governanceai.com/v1/guardrails/evaluate',
9    headers={
10        'Authorization': f'Bearer {api_key}',
11        'Content-Type': 'application/json'
12    },
13    json={
14        'messages': [
15            {
16                'role': 'user',
17                'content': 'What is the capital of France?'
18            }
19        ],
20        'context': {
21            'org_id': org_id,
22            'user_id': 'user_demo',
23            'session_id': 'session_123'
24        }
25    }
26)
27
28print(response.json())

Option C: Node.js

1const https = require('https');
2
3const apiKey = process.env.GOVERNANCEAI_API_KEY;
4const orgId = process.env.GOVERNANCEAI_ORG_ID;
5
6const options = {
7  hostname: 'api.governanceai.com',
8  path: '/v1/guardrails/evaluate',
9  method: 'POST',
10  headers: {
11    'Authorization': `Bearer ${apiKey}`,
12    'Content-Type': 'application/json'
13  }
14};
15
16const req = https.request(options, (res) => {
17  let data = '';
18  res.on('data', (chunk) => { data += chunk; });
19  res.on('end', () => { console.log(JSON.parse(data)); });
20});
21
22req.write(JSON.stringify({
23  messages: [
24    {
25      role: 'user',
26      content: 'What is the capital of France?'
27    }
28  ],
29  context: {
30    org_id: orgId,
31    user_id: 'user_demo',
32    session_id: 'session_123'
33  }
34}));
35
36req.end();

Step 5: Review the Response (1 min)

You should receive a response like:

1{
2  "decision": "allow",
3  "policy_violations": [],
4  "risk_score": 0.05,
5  "metadata": {
6    "evaluation_time_ms": 45,
7    "policies_evaluated": 12,
8    "org_id": "org_123abc..."
9  }
10}

Response Fields:

  • decision - Whether the message was allowed or blocked
  • policy_violations - List of policies that were violated (if any)
  • risk_score - Overall risk score (0-1, where 1 is highest risk)
  • metadata - Additional info about the evaluation

Understanding the Response

If decision is “allow” ✅

Your message passed all active guardrails. The LLM response is safe to display to the user.

1{
2  "decision": "allow",
3  "policy_violations": [],
4  "risk_score": 0.02
5}

If decision is “block” ❌

Your message violated one or more policies. You should not display the response to the user.

1{
2  "decision": "block",
3  "policy_violations": [
4    {
5      "policy_id": "policy_toxicity",
6      "policy_name": "Block Toxic Content",
7      "severity": "high"
8    }
9  ],
10  "risk_score": 0.92
11}

If decision is “transform”

The message was modified to comply with policies before being returned.

1{
2  "decision": "transform",
3  "policy_violations": ["policy_pii_redaction"],
4  "transformed_response": "The person is located in [REDACTED]",
5  "risk_score": 0.15
6}

Next Steps

Congratulations! 🎉

You’ve successfully made your first GovernanceAI API call. Here’s what to explore next:

  • Set Up Guardrails

    • Create custom guardrails specific to your use case
    • Configure policy rules and thresholds

  • Create Policies

    • Define organization-wide governance policies
    • Test policies before rolling out to production

  • Integrate with Your Stack

    • Connect with GitHub for code scanning
    • Set up Jira for issue tracking
    • Integrate with your favorite LLM provider

  • Code Examples

    • Python client library setup
    • Node.js integration patterns
    • Advanced API patterns

  • Core Concepts

    • Deep dive into guardrails and policies
    • Learn about AI Bill of Materials
    • Understand red-teaming framework

Common Issues

Error: 401 Unauthorized

Problem: Invalid or missing API key

Solution:

  • Verify your API key is correct
  • Make sure it hasn’t been rotated
  • Check the Authorization header format: Authorization: Bearer <key>

Error: 403 Forbidden

Problem: API key doesn’t have permission

Solution:

  • Go to Settings → API Keys
  • Verify your key has runtime:execute scope
  • Generate a new key with correct permissions

Error: Network timeout

Problem: Connection to API is slow

Solution:

  • Check your internet connection
  • Try again in a few seconds
  • Contact support if issue persists

Troubleshooting Checklist

  • API key is correct and starts with gak_
  • Organization ID is correct and starts with org_
  • Using HTTPS (not HTTP)
  • Authorization header format is correct
  • API key has runtime:execute scope
  • API key hasn’t expired
  • Network can reach api.governanceai.com
  • Request body is valid JSON

Need Help?

You’re all set! Start building with GovernanceAI. 🚀