​
Overview

API keys provide a secure way to authenticate API requests without requiring user credentials. They are particularly useful for server-to-server communication and for integrating with the workflow system.

​
API Key Structure

  • Format: sk-{random_string}
  • Example: sk-ABCDEFGhijklmnoPQRSTuvwxyz1234567890ABCDEFG

​
API Key Properties

  • Name: Human-readable name for the key
  • Organization: Associated organization
  • Team: Optional team association
  • Workflow ID: Optional specific workflow restriction
  • Expiration: Optional expiry date

​
Creating an API Key

​
Accessing the API Key Page

  1. Log into your Gaife account
  2. Navigate to your organization dashboard
  3. In the left sidebar menu, find and click on “Developer API” or “API Keys”
  4. The path follows this structure: /organizations/[orgId]/api-access

​
Creating a New API Key

  1. On the API Keys page, click the ”+ Create new API key” button in the top-right corner
  2. A dialog will appear asking you to name your key
  3. Enter a descriptive name for your API key (e.g., “Production API”, “Development Testing”, etc.)
  4. Click “Generate Key”
  5. Your new API key will be displayed - copy it

​
Using API Keys in Requests

API keys are sent as Bearer tokens in the Authorization header: 
Authorization: Bearer sk-ABCDEFGhijklmnoPQRSTuvwxyz1234567890ABCDEFG

​
Example: Developer Workflow Triggers

​
Endpoint

POST /developer/api/workflows/{workflow_id}/trigger/sync

​
Description

Triggers a workflow synchronously

​
Headers

Authorization: Bearer {API_KEY}

​
Request Body

{
  "human_msg": "Message to trigger the workflow if any",
  "file_urls": ["url1", "url2"] // Optional
}

​
Example: Developer Workflow Status

​
Endpoint

GET /developer/api/workflow_instances/{workflow_instance_id}/status

​
Description

Gets the status of a workflow instance

​
Headers

Authorization: Bearer {API_KEY}

​
API Key Restrictions

  • Organization Restriction: API keys can only be used for the organization they belong to
  • Workflow Restriction: If a workflow_id is specified when creating the key, the key can only be used for that specific workflow
  • Expiration: Keys with an expiration date will be invalidated after that date

​
Security Considerations

  • Keep API Keys Secure: Store them securely and never expose them in client-side code
  • Use Workflow-Specific Keys: For improved security, create keys with workflow_id restrictions
  • Rotation: Regularly rotate API keys to minimize security risks
  • Monitor Usage: The system tracks the last_used_at timestamp for auditing

​
Error Responses

​
Invalid API Key

{
  "error": "Authentication failed",
  "detail": "Invalid or inactive API key."
}
Status: 401 Unauthorized

​
Unauthorized Workflow Access

{
  "error": "API key is not authorized for this workflow"
}

​
Missing API Key

{
  "error": "Authentication failed",
  "detail": "Valid API key required. Please include it in the Authorization header as 'Bearer <your-api-key>'."
}

​
Best Practices

  • Create different API keys for different integrations to easily revoke access if needed
  • Use team-specific keys when appropriate to limit access scope
  • Specify a workflow_id when the key will only be used for a specific workflow
  • Set expiration dates on keys that are meant for temporary use