# API Key Management

The API Key Management endpoints provide the ability to list, create, update, and delete reusable provider API keys within your workspaces. These keys enable you to decouple credentials from individual storage units or AI models, facilitating better credential rotation, sharing, and centralized management.

## Overview

Provider API Keys act as a centralized vault for your cloud and AI provider credentials. Instead of entering your AWS access key or OpenAI secret directly into every storage bucket or AI LLM configuration, you can save them once as a Provider API Key and reference that key across multiple resources.

### Key Characteristics

* **Workspace-Scoped**: Each API key is associated with a specific workspace, governing who can view and use it.
* **Reusable**: A single API key can be linked to multiple Storage Units and AI LLMs.
* **Encrypted Storage**: Secrets (like AWS Secret Keys or API tokens) are encrypted before being stored in the database.
* **Safe Deletion**: An API key cannot be deleted if it is still actively being used by any Storage Unit or AI LLM.

## Supported Providers

Provider API keys can be created for any provider type supported by Flashback, including:

* **AWS** - Amazon Web Services (S3, Bedrock)
* **GCP** - Google Cloud Platform (GCS, Vertex AI)
* **AZURE** - Microsoft Azure (Blob Storage, Azure OpenAI)
* **OPENAI** - OpenAI
* **ANTHROPIC** - Anthropic
* And any other supported `ProviderType`.

## API Key Management Calls

### Key Management

| Method                                                     | API Reference                                                                                                                                 | Description                              |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| <mark style="color:green;">`GET`</mark> `/apikeys`         | [**get\_\_apikeys**](https://docs.flashback.tech/support-reference/platform-api-reference/api-key-management/get__apikeys)                    | List available API keys for a workspace. |
| <mark style="color:orange;">`POST`</mark> `/apikeys`       | [**post\_\_apikeys**](https://docs.flashback.tech/support-reference/platform-api-reference/api-key-management/post__apikeys)                  | Create a new provider API key.           |
| <mark style="color:blue;">`PUT`</mark> `/apikeys/{uuid}`   | [**put\_\_apikeys\_{uuid}**](https://docs.flashback.tech/support-reference/platform-api-reference/api-key-management/put__apikeys_uuid)       | Update an existing API key's properties. |
| <mark style="color:red;">`DELETE`</mark> `/apikeys/{uuid}` | [**delete\_\_apikeys\_{uuid}**](https://docs.flashback.tech/support-reference/platform-api-reference/api-key-management/delete__apikeys_uuid) | Delete a provider API key.               |

## Common Use Cases

### 1. Centralized Credential Creation

Create an API key once and use it to configure multiple buckets.

```typescript
// Create the API Key
const apiKeyResponse = await client.createApiKey({
  workspaceId: "workspace-123",
  key: "AKIAIOSFODNN7EXAMPLE",
  secret: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  provider: "AWS"
});

// Use it for Bucket A
await client.createStorageBucket({
  workspaceId: "workspace-123",
  name: "bucket-a",
  apiKeyUuid: apiKeyResponse.apiKeyId, // Link the key
  // ... other bucket settings
});

// Use it for Bucket B
await client.createStorageBucket({
  workspaceId: "workspace-123",
  name: "bucket-b",
  apiKeyUuid: apiKeyResponse.apiKeyId, // Link the same key
  // ... other bucket settings
});
```

### 2. Monitoring Key Usage

Determine how many resources are relying on a specific credential before attempting to rotate or delete it.

```typescript
const response = await client.getApiKeys("workspace-123");

response.apiKeys.forEach(key => {
  console.log(`Provider: ${key.provider}, Key: ${key.key}`);
  console.log(`In use by: ${key.bucket_count} buckets and ${key.aillm_count} AI models`);
});
```

### 3. Credential Rotation

Update the credentials without having to individually update every single bucket or AI model that uses them.

```typescript
// Update the API Key's secret
await client.updateApiKey("apikey-uuid-123", {
  secret: "NEW_SECRET_KEY_VALUE"
});
// All buckets and AI models linked to "apikey-uuid-123" will instantly 
// start using the new secret for future operations.
```

## Security Best Practices

### 1. Principle of Least Privilege

Ensure your provider API keys only have the permissions necessary in the target cloud (e.g., scoped IAM roles in AWS or GCP).

### 2. Understand Workspace Isolation

API keys belong to workspaces. Ensure you create keys in the appropriate workspace so that only authorized team members can utilize those credentials to provision resources.

### 3. Safe Deletion Protocol

The Flashback platform protects you from accidental deletions by blocking the removal of any API key that is actively linked to a bucket or AI model. Before deleting a key, you must first migrate or delete the dependent resources.

## Error Handling

Common error scenarios and how to handle them:

### 400 Bad Request (Deletion Constraint)

**Cause:** Attempting to delete an API key that is still in use.

```typescript
try {
  await client.deleteApiKey("apikey-uuid-123");
} catch (error) {
  if (error.status === 400) {
    console.error("Cannot delete: Key is in use by active buckets or AI models.");
    // Action: Use getApiKeys to check bucket_count and aillm_count
  }
}
```

### 403 Forbidden

**Cause:** User doesn't have read/write access to the workspace the API key belongs to.

```typescript
try {
  await client.getApiKeys("workspace-123");
} catch (error) {
  if (error.status === 403) {
    console.error("Access denied: Check workspace permissions");
  }
}
```

## Next Steps

1. Review your existing Storage Units and consider migrating them to use centralized API keys.
2. Update your provisioning scripts to utilize `POST /apikeys` before creating new resources.