Saltar al contenido principal

Managing API Keys

Learn how to create and manage API keys for programmatic access to your AgentsGT agents.

What are API Keys?​

API keys allow you to interact with your agents programmatically — from your own applications, websites, or backend services. Every request to the AgentsGT /v1 API requires an API key for authentication.

Each API key has two parts:

  • Public key (pk_xxx) — Identifies the key. Can be included in client-side code
  • Secret key (sk_xxx) — Authenticates the request. Must be kept secure and never exposed publicly

Together, they form the credentials used in API requests:

Authorization: Bearer pk_xxx:sk_xxx

Creating an API Key​

Step 1: Navigate to API Keys​

  1. Go to Settings → API Keys (or navigate to /org/{organizationId}/settings/api-keys)

Step 2: Create a New Key​

  1. Click "Create API Key"
  2. Enter a name for the key (e.g., "Production Website", "Mobile App", "Development")
  3. Optionally add allowed domains (comma-separated) to restrict where the key can be used
  4. Click "Create"

Step 3: Save Your Key​

After creation, a dialog will display your full key pair:

Public Key: pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Secret Key: sk_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0f9e8d7c6b5a4z3y2x1w0

Important: The secret key is only shown once. Copy it immediately and store it securely. You will not be able to see it again.

  • Environment variables — Store keys in .env files (never commit to version control)
  • Secret managers — Use AWS Secrets Manager, Google Secret Manager, or similar services
  • Secure vaults — Use tools like HashiCorp Vault for team environments

Managing Existing Keys​

Viewing Your Keys​

Go to Settings → API Keys to see all your organization's keys:

ColumnDescription
NameThe descriptive name you gave the key
Public KeyThe pk_xxx portion (safe to display)
Last UsedWhen the key was last used for an API call
StatusEnabled or disabled

Enabling/Disabling a Key​

  1. Find the key in the list
  2. Toggle the enabled/disabled switch
  3. Disabled keys immediately stop working for API authentication

Use this to temporarily disable a key without deleting it (e.g., if you suspect it may be compromised).

Managing Allowed Domains​

Allowed domains restrict which websites can use the API key. This is useful for client-side integrations where the key is visible in the source code.

Example domains:

  • example.com — Exact domain match
  • *.example.com — Wildcard: matches any subdomain

To update allowed domains:

  1. Click on the key in the list
  2. Edit the allowed domains field
  3. Click Save

Note: If no domains are specified and a secret key is provided, the key works from any origin.

Deleting a Key​

  1. Find the key in the list
  2. Click the delete button
  3. Confirm the deletion

Warning: Deleting a key is permanent and immediate. Any applications using this key will stop working.

Using API Keys​

Authentication Header​

Include your key in every API request:

Authorization: Bearer pk_xxx:sk_xxx

Example Request​

curl -X GET https://agentsgt.com/api/v1/agents \
  -H "Authorization: Bearer pk_a1b2c3d4e5f6:sk_z9y8x7w6v5u4"

What Happens During Authentication​

  1. The API extracts the public key and secret key from the header
  2. Validates the key exists, is enabled, and hasn't expired
  3. If the secret key is provided, origin validation is skipped
  4. If only the public key is provided, the request origin is checked against allowed domains
  5. The organization ID associated with the key is passed to the endpoint

Security Best Practices​

Do​

  • ✓ Use separate keys for development and production
  • ✓ Rotate keys periodically (create new key, update your apps, then delete the old key)
  • ✓ Set allowed domains for client-side integrations
  • ✓ Store secret keys in environment variables or secret managers
  • ✓ Monitor the "Last Used" timestamp for unexpected activity
  • ✓ Disable keys you're not actively using

Don't​

  • ✗ Commit API keys to version control (Git, SVN, etc.)
  • ✗ Share secret keys over insecure channels (email, chat)
  • ✗ Use the same key across multiple applications
  • ✗ Embed secret keys in client-side JavaScript on public websites
  • ✗ Ignore suspicious "Last Used" activity

What's Next?​