AI Provider Keys

Manage API keys for third-party AI providers (OpenAI, Anthropic, Google, etc.). Provider keys are stored encrypted and used by the AI Gateway to authenticate requests to upstream providers. The raw API key value is never returned after creation.

---

ProviderKey Object

{
  "id": "pk_abc123",
  "name": "OpenAI Production Key",
  "provider": "openai",
  "description": "Production API key for OpenAI models",
  "providerOrganization": "org-abc123",
  "owner": "user_abc123",
  "organizationId": "org_abc123",
  "isActive": true,
  "lastUsedAt": "2025-02-06T18:30:00.000Z",
  "lastTestedAt": "2025-02-06T12:00:00.000Z",
  "testResult": {
    "success": true,
    "message": "Key is valid",
    "testedAt": "2025-02-06T12:00:00.000Z"
  },
  "maskedKey": "sk-...xyz9",
  "createdAt": "2025-01-10T08:00:00.000Z",
  "updatedAt": "2025-02-06T12:00:00.000Z"
}

---

GET /api/v1/ai/provider-keys

List provider keys

Returns a paginated list of provider keys for the current user's organization. API key values are never included; only masked keys are returned.

Scope: ai-gateway:read

Parameters:

Name	In	Type	Required	Description
provider	query	string	No	Filter by provider: openai, anthropic, google, huggingface, etc.
status	query	string	No	Filter by status: active, inactive
search	query	string	No	Search by key name
limit	query	integer	No	Max results (default: 50, max: 200)
offset	query	integer	No	Pagination offset
sort	query	string	No	Sort field (default: -createdAt)

Response: 200 OK (paginated)

{
  "data": [
    {
      "id": "pk_abc123",
      "name": "OpenAI Production Key",
      "provider": "openai",
      "description": "Production API key for OpenAI models",
      "providerOrganization": "org-abc123",
      "owner": "user_abc123",
      "organizationId": "org_abc123",
      "isActive": true,
      "lastUsedAt": "2025-02-06T18:30:00.000Z",
      "lastTestedAt": "2025-02-06T12:00:00.000Z",
      "testResult": {
        "success": true,
        "message": "Key is valid",
        "testedAt": "2025-02-06T12:00:00.000Z"
      },
      "maskedKey": "sk-...xyz9",
      "createdAt": "2025-01-10T08:00:00.000Z",
      "updatedAt": "2025-02-06T12:00:00.000Z"
    }
  ],
  "meta": { "total": 4, "limit": 50, "offset": 0, "hasMore": false, "requestId": "req_abc123" }
}

---

POST /api/v1/ai/provider-keys

Create a provider key

Registers a new provider API key. The key is encrypted at rest and can only be used by the AI Gateway for upstream requests.

Scope: ai-gateway:write

Request Body:

{
  "name": "OpenAI Production Key",
  "provider": "openai",
  "apiKey": "sk-proj-abc123def456ghi789",
  "description": "Production API key for OpenAI models",
  "providerOrganization": "org-abc123"
}

Field	Type	Required	Description
name	string	Yes	Human-readable key name
provider	string	Yes	Provider: openai, anthropic, google, huggingface, cohere, mistral, etc.
apiKey	string	Yes	The raw API key value
description	string	No	Key description
providerOrganization	string	No	Provider-specific organization ID (e.g., OpenAI org ID)

Response: 201 Created

{
  "data": {
    "id": "pk_abc123",
    "name": "OpenAI Production Key",
    "provider": "openai",
    "description": "Production API key for OpenAI models",
    "providerOrganization": "org-abc123",
    "owner": "user_abc123",
    "organizationId": "org_abc123",
    "isActive": true,
    "maskedKey": "sk-...789",
    "createdAt": "2025-02-07T10:00:00.000Z",
    "updatedAt": "2025-02-07T10:00:00.000Z"
  },
  "meta": { "requestId": "req_abc123" }
}

warning

The raw apiKey value is stored encrypted and is never returned in any API response. Only the maskedKey (last 4 characters) is shown.

---

GET /api/v1/ai/provider-keys/:id

Get a provider key

Returns a single provider key with safe fields only. The raw API key value is never included.

Scope: ai-gateway:read

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes	Provider key ID

Response: 200 OK

{
  "data": {
    "id": "pk_abc123",
    "name": "OpenAI Production Key",
    "provider": "openai",
    "description": "Production API key for OpenAI models",
    "providerOrganization": "org-abc123",
    "owner": "user_abc123",
    "organizationId": "org_abc123",
    "isActive": true,
    "lastUsedAt": "2025-02-06T18:30:00.000Z",
    "lastTestedAt": "2025-02-06T12:00:00.000Z",
    "testResult": {
      "success": true,
      "message": "Key is valid",
      "testedAt": "2025-02-06T12:00:00.000Z"
    },
    "maskedKey": "sk-...xyz9",
    "createdAt": "2025-01-10T08:00:00.000Z",
    "updatedAt": "2025-02-06T12:00:00.000Z"
  },
  "meta": { "requestId": "req_abc123" }
}

---

PUT /api/v1/ai/provider-keys/:id

Update a provider key

Updates provider key properties. If apiKey is provided, the stored key is replaced. Only provided fields are changed.

Scope: ai-gateway:write

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes	Provider key ID

Request Body:

{
  "name": "OpenAI Production Key (Rotated)",
  "apiKey": "sk-proj-new-key-value",
  "description": "Rotated key as of Feb 2025"
}

Field	Type	Required	Description
name	string	No	Updated key name
apiKey	string	No	New raw API key value (replaces existing)
description	string	No	Updated description
providerOrganization	string	No	Updated provider organization ID

Response: 200 OK

{
  "data": {
    "id": "pk_abc123",
    "name": "OpenAI Production Key (Rotated)",
    "provider": "openai",
    "maskedKey": "sk-...lue",
    "updatedAt": "2025-02-07T12:00:00.000Z"
  },
  "meta": { "requestId": "req_abc123" }
}

---

DELETE /api/v1/ai/provider-keys/:id

Delete a provider key

Permanently removes a provider key. Models using this key will lose access to the upstream provider.

Scope: ai-gateway:write

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes	Provider key ID

Response: 204 No Content

caution

Deleting a provider key will immediately prevent any AI models using this key from making inference requests. Ensure no active models depend on this key before deleting.

---

POST /api/v1/ai/provider-keys/:id/test

Test a provider key

Validates the provider key by making a lightweight API call to the upstream provider. This does not consume tokens or incur costs.

Scope: ai-gateway:read

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes	Provider key ID

Response: 200 OK

{
  "data": {
    "success": true,
    "message": "Key is valid and has access to the provider API",
    "testedAt": "2025-02-07T12:00:00.000Z"
  },
  "meta": { "requestId": "req_abc123" }
}

On failure:

{
  "data": {
    "success": false,
    "message": "Authentication failed: invalid API key",
    "testedAt": "2025-02-07T12:00:00.000Z"
  },
  "meta": { "requestId": "req_abc123" }
}