# API Keys Resource

## Description

Securely generate and manage API keys used by organizations to authenticate webhook requests and access platform resources programmatically

### API Key Document Format

```ts
{
  "keyHash": string,
  "name": string,
  "createdAt": number,
  "expiresAt"?: number,
  "revoked": boolean,
  "lastUsedAt"?: number
}
```

***

### Create API Key - (_Org Admin_)

`POST /organizations/:orgId/api-keys`

**Example Request:**

```json
{
  "name": "Webhook Key",
  "expiresAt": 1753200000000
}
```

**Example Response (201 Created):**

```json
{
  "success": true,
  "message": "API Key created successfully.",
  "data": {
    "_id": "wU1KlPLcvntXyaDlGSYY",
    "apiKey": "ta_org_5FLBfdCUBOVOniy7cmUlVzn1Eda2fcnVtdUG91XG",
    "name": "Webhook Key",
    "createdAt": 1753805472282,
    "updatedAt": 1753805472282,
    "schemaVersion": 1,
    "revoked": false,
    "expiresAt": 1753200000000
  }
}
```

***

### Get All API Keys (Metadata Only)

`GET /organizations/:orgId/api-keys`

**Example Response (200 OK):**

```json
{
  "success": true,
  "message": "retrieved api keys successfully.",
  "data": [
    {
      "_id": "key1",
      "name": "Webhook Key",
      "createdAt": 1722444800000,
      "expiresAt": 1753200000000,
      "schemaVersion": 1,
      "revoked": false
    }
  ]
}
```

***

### Get API Key by ID (Metadata Only)

`GET /organizations/:orgId/api-keys/:keyId`

**Example Response (200 OK):**

```json
{
  "success": true,
  "message": "retrieved api key metadata successfully.",
  "data": {
    "_id": "key1",
    "name": "Webhook Key",
    "createdAt": 1722444800000,
    "expiresAt": 1753200000000,
    "schemaVersion": 1,
    "revoked": false
  }
}
```

***

### Revoke API Key

`PATCH /organizations/:orgId/api-keys/:keyId`

**Example Request:**

```json
{
  "revoked": true
}
```

**Example Response (200 OK):**

```json
{
  "success": true,
  "message": "API Key updated successfully.",
  "data": {
    "revoked": true
  }
}
```

***

### Delete API Key

`DELETE /organizations/:orgId/api-keys/:keyId`

**Example Response (200 OK):**

```json
{
  "success": true,
  "message": "api key deleted successfully."
}
```
