> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gaife.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Key Usage

> Learn how to create, manage, and use API keys for secure authentication

## 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

```json theme={null}
{
  "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

```json theme={null}
{
  "error": "Authentication failed",
  "detail": "Invalid or inactive API key."
}
```

Status: 401 Unauthorized

### Unauthorized Workflow Access

```json theme={null}
{
  "error": "API key is not authorized for this workflow"
}
```

### Missing API Key

```json theme={null}
{
  "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