mirror of
https://github.com/prowler-cloud/prowler.git
synced 2026-07-23 12:31:54 +00:00
docs(api): use mintlify for API specs
This commit is contained in:
pedrooot
@@ -0,0 +1,182 @@
|
||||
---
|
||||
title: "Create API Key"
|
||||
api: "POST /api/v1/api-keys"
|
||||
description: "Create a new API key for the tenant."
|
||||
---
|
||||
|
||||
Create a new API key for programmatic access to the Prowler API. The API key will be returned in the response and should be stored securely as it cannot be retrieved later.
|
||||
|
||||
## Request Body
|
||||
|
||||
The request must follow the JSON:API specification format:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"type": "api-keys",
|
||||
"attributes": {
|
||||
"name": "string",
|
||||
"expires_at": "2024-12-31T23:59:59Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Attributes
|
||||
|
||||
- `name` (required) - A descriptive name for the API key
|
||||
- `expires_at` (optional) - Expiration date for the API key in ISO 8601 format
|
||||
|
||||
## Example Request
|
||||
|
||||
```bash
|
||||
curl -X POST "https://api.prowler.com/api/v1/api-keys" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-H "Content-Type: application/vnd.api+json" \
|
||||
-d '{
|
||||
"data": {
|
||||
"type": "api-keys",
|
||||
"attributes": {
|
||||
"name": "Production API Key",
|
||||
"expires_at": "2025-12-31T23:59:59Z"
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
### Success Response (201 Created)
|
||||
|
||||
Returns the created API key **including the full key value** (only shown once):
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"type": "api-keys",
|
||||
"id": "api-key-uuid",
|
||||
"attributes": {
|
||||
"name": "Production API Key",
|
||||
"prefix": "pk_live_abc123",
|
||||
"api_key": "pk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
|
||||
"expires_at": "2025-12-31T23:59:59Z",
|
||||
"revoked": false,
|
||||
"inserted_at": "2024-01-15T10:30:00Z",
|
||||
"last_used_at": null
|
||||
},
|
||||
"relationships": {
|
||||
"entity": {
|
||||
"data": {
|
||||
"type": "users",
|
||||
"id": "user-uuid"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response Fields
|
||||
|
||||
- `id` - Unique UUID for the API key record
|
||||
- `name` - Descriptive name you provided (3-100 characters)
|
||||
- `prefix` - First characters of the key (for identification, read-only)
|
||||
- `api_key` - **Full API key value** (only returned on creation, read-only)
|
||||
- `expires_at` - Expiration date in ISO 8601 format (optional)
|
||||
- `revoked` - Whether key has been revoked (always false on creation, read-only)
|
||||
- `inserted_at` - When key was created (read-only)
|
||||
- `last_used_at` - Last usage timestamp (null initially, read-only)
|
||||
|
||||
### Error Responses
|
||||
|
||||
**400 Bad Request** - Invalid expiration date
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{
|
||||
"status": "400",
|
||||
"title": "Invalid Expiration Date",
|
||||
"detail": "Expiration date must be in the future"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**422 Unprocessable Entity** - Missing required fields
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{
|
||||
"status": "422",
|
||||
"title": "Validation Error",
|
||||
"detail": "Name is required",
|
||||
"source": {
|
||||
"pointer": "/data/attributes/name"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**429 Too Many Requests** - API key limit reached
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{
|
||||
"status": "429",
|
||||
"title": "API Key Limit Exceeded",
|
||||
"detail": "Maximum of 10 active API keys per tenant. Revoke unused keys to create new ones."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Example
|
||||
|
||||
After creating the API key, use it to authenticate API requests:
|
||||
|
||||
```bash
|
||||
# Save the API key
|
||||
API_KEY="pk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
|
||||
|
||||
# Use it in requests
|
||||
curl -X GET "https://api.prowler.com/api/v1/providers" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H "Content-Type: application/vnd.api+json"
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. **Store Securely**: Save the API key in a secure location immediately (password manager, secrets vault, environment variables)
|
||||
2. **Never Commit**: Do not commit API keys to version control systems
|
||||
3. **Use Environment Variables**: Store keys in environment variables, not in code
|
||||
4. **Set Expiration**: Always set an expiration date for API keys (recommended: 90 days)
|
||||
5. **Rotate Regularly**: Rotate API keys every 90 days
|
||||
6. **Limit Scope**: Use separate API keys for different environments (dev, staging, production)
|
||||
7. **Monitor Usage**: Regularly check `last_used_at` to identify unused keys
|
||||
8. **Revoke Unused**: Revoke API keys that are no longer needed
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
Use descriptive names that include:
|
||||
- **Environment**: Production, Staging, Development
|
||||
- **Purpose**: CI/CD, Dashboard, Integration
|
||||
- **Owner/Team**: Security Team, DevOps, Monitoring
|
||||
|
||||
Examples:
|
||||
- "Production CI/CD Pipeline"
|
||||
- "Staging Dashboard API Access"
|
||||
- "Security Team Automation"
|
||||
- "JIRA Integration - Production"
|
||||
|
||||
<Warning>
|
||||
**CRITICAL:** The API key is only shown once in the creation response. It cannot be retrieved later. If you lose the key, you must revoke it and create a new one. Store it securely immediately after creation.
|
||||
</Warning>
|
||||
|
||||
<Note>
|
||||
API keys have the same permissions as the user who created them. For automated systems, consider creating a dedicated service account with limited permissions.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
**Automation Tip:** API keys are ideal for CI/CD pipelines, scheduled scans, and integrations. Unlike JWT tokens, they don't expire hourly and don't require refresh logic.
|
||||
</Tip>
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
title: "List API Keys"
|
||||
api: "GET /api/v1/api-keys"
|
||||
description: "Retrieve a list of API keys for the tenant, with filtering support."
|
||||
---
|
||||
|
||||
Retrieve a list of all API keys associated with your tenant. This endpoint supports various filtering options to help you find specific keys.
|
||||
|
||||
## Query Parameters
|
||||
|
||||
### Filtering
|
||||
|
||||
- `filter[name]` - Filter by exact API key name
|
||||
- `filter[name__icontains]` - Filter by API key name (case-insensitive)
|
||||
- `filter[prefix]` - Filter by API key prefix
|
||||
- `filter[revoked]` - Filter by revocation status (boolean)
|
||||
- `filter[expires_at]`, `filter[expires_at__gte]`, `filter[expires_at__lte]` - Filter by expiration date
|
||||
- `filter[inserted_at]`, `filter[inserted_at__gte]`, `filter[inserted_at__lte]` - Filter by creation date
|
||||
- `filter[search]` - General search term
|
||||
|
||||
### Pagination
|
||||
|
||||
- `page[number]` - Page number to retrieve
|
||||
- `page[size]` - Number of results per page
|
||||
|
||||
### Sorting
|
||||
|
||||
- `sort` - Field to sort by. Available options: `name`, `-name`, `prefix`, `-prefix`, `revoked`, `-revoked`, `inserted_at`, `-inserted_at`, `expires_at`, `-expires_at`
|
||||
|
||||
### Field Selection
|
||||
|
||||
- `fields[api-keys]` - Specify which fields to return: `name`, `prefix`, `expires_at`, `revoked`, `inserted_at`, `last_used_at`, `entity`
|
||||
|
||||
### Include Related Resources
|
||||
|
||||
- `include` - Include related resources. Available: `entity`
|
||||
|
||||
## Example Request
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.prowler.com/api/v1/api-keys?page[size]=10&sort=-inserted_at" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/vnd.api+json"
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
### Success Response (200 OK)
|
||||
|
||||
Returns a paginated list of API keys with their metadata:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"type": "api-keys",
|
||||
"id": "api-key-uuid-1",
|
||||
"attributes": {
|
||||
"name": "Production CI/CD Pipeline",
|
||||
"prefix": "pk_live_abc123",
|
||||
"expires_at": "2025-12-31T23:59:59Z",
|
||||
"revoked": false,
|
||||
"inserted_at": "2024-01-15T10:30:00Z",
|
||||
"last_used_at": "2024-01-20T14:22:00Z"
|
||||
},
|
||||
"relationships": {
|
||||
"entity": {
|
||||
"data": {
|
||||
"type": "users",
|
||||
"id": "user-uuid"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "api-keys",
|
||||
"id": "api-key-uuid-2",
|
||||
"attributes": {
|
||||
"name": "Staging Dashboard API Access",
|
||||
"prefix": "pk_live_def456",
|
||||
"expires_at": null,
|
||||
"revoked": false,
|
||||
"inserted_at": "2024-01-10T08:15:00Z",
|
||||
"last_used_at": null
|
||||
},
|
||||
"relationships": {
|
||||
"entity": {
|
||||
"data": {
|
||||
"type": "users",
|
||||
"id": "user-uuid"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"meta": {
|
||||
"page": {
|
||||
"number": 1,
|
||||
"size": 20,
|
||||
"total": 2,
|
||||
"total_pages": 1
|
||||
}
|
||||
},
|
||||
"links": {
|
||||
"self": "https://api.prowler.com/api/v1/api-keys?page[number]=1",
|
||||
"first": "https://api.prowler.com/api/v1/api-keys?page[number]=1",
|
||||
"last": "https://api.prowler.com/api/v1/api-keys?page[number]=1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response Fields
|
||||
|
||||
- `id` (UUID) - Unique identifier for the API key record
|
||||
- `name` (string) - Descriptive name (3-100 characters)
|
||||
- `prefix` (string, read-only) - First characters of the key for identification
|
||||
- `expires_at` (datetime, nullable) - Expiration date in ISO 8601 format
|
||||
- `revoked` (boolean, read-only) - Whether key has been revoked
|
||||
- `inserted_at` (datetime, read-only) - When key was created
|
||||
- `last_used_at` (datetime, nullable, read-only) - Last usage timestamp
|
||||
|
||||
<Note>
|
||||
The full API key value is never returned after creation. Only the prefix is shown for identification purposes.
|
||||
</Note>
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
title: "Retrieve API Key"
|
||||
api: "GET /api/v1/api-keys/{id}"
|
||||
description: "Fetch detailed information about a specific API key by its ID."
|
||||
---
|
||||
|
||||
Retrieve detailed information about a specific API key. Note that the full API key value is never returned, only metadata about the key.
|
||||
|
||||
## Path Parameters
|
||||
|
||||
- `id` (required) - The UUID of the API key to retrieve
|
||||
|
||||
## Query Parameters
|
||||
|
||||
### Field Selection
|
||||
|
||||
- `fields[api-keys]` - Specify which fields to return: `name`, `prefix`, `expires_at`, `revoked`, `inserted_at`, `last_used_at`, `entity`
|
||||
|
||||
### Include Related Resources
|
||||
|
||||
- `include` - Include related resources. Available: `entity`
|
||||
|
||||
## Example Request
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.prowler.com/api/v1/api-keys/{id}" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/vnd.api+json"
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
### Success Response (200 OK)
|
||||
|
||||
Returns detailed metadata about the API key:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"type": "api-keys",
|
||||
"id": "api-key-uuid",
|
||||
"attributes": {
|
||||
"name": "Production CI/CD Pipeline",
|
||||
"prefix": "pk_live_abc123",
|
||||
"expires_at": "2025-12-31T23:59:59Z",
|
||||
"revoked": false,
|
||||
"inserted_at": "2024-01-15T10:30:00Z",
|
||||
"last_used_at": "2024-01-20T14:22:00Z"
|
||||
},
|
||||
"relationships": {
|
||||
"entity": {
|
||||
"data": {
|
||||
"type": "users",
|
||||
"id": "user-uuid"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response Fields
|
||||
|
||||
- `id` (UUID) - Unique identifier for the API key record
|
||||
- `name` (string) - Descriptive name (3-100 characters)
|
||||
- `prefix` (string, read-only) - First characters of the key for identification
|
||||
- `expires_at` (datetime, nullable) - Expiration date in ISO 8601 format
|
||||
- `revoked` (boolean, read-only) - Whether key has been revoked
|
||||
- `inserted_at` (datetime, read-only) - When key was created
|
||||
- `last_used_at` (datetime, nullable, read-only) - Last usage timestamp
|
||||
|
||||
### Error Responses
|
||||
|
||||
**404 Not Found** - API key does not exist
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{
|
||||
"status": "404",
|
||||
"title": "Not Found",
|
||||
"detail": "API key not found"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
The full API key value is never returned after creation. Only the prefix is shown for identification purposes.
|
||||
</Note>
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: "Revoke API Key"
|
||||
api: "DELETE /api/v1/api-keys/{id}/revoke"
|
||||
description: "Revoke an API key by its ID. This action is irreversible."
|
||||
---
|
||||
|
||||
Revoke an API key, preventing it from being used for further API requests. This action cannot be undone.
|
||||
|
||||
## Path Parameters
|
||||
|
||||
- `id` (required) - The UUID of the API key to revoke
|
||||
|
||||
## Example Request
|
||||
|
||||
```bash
|
||||
curl -X DELETE "https://api.prowler.com/api/v1/api-keys/{id}/revoke" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/vnd.api+json"
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
### Success Response (200 OK)
|
||||
|
||||
Returns the API key with `revoked` status set to `true`:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"type": "api-keys",
|
||||
"id": "api-key-uuid",
|
||||
"attributes": {
|
||||
"name": "Production CI/CD Pipeline",
|
||||
"prefix": "pk_live_abc123",
|
||||
"expires_at": "2025-12-31T23:59:59Z",
|
||||
"revoked": true,
|
||||
"inserted_at": "2024-01-15T10:30:00Z",
|
||||
"last_used_at": "2024-01-20T14:22:00Z"
|
||||
},
|
||||
"relationships": {
|
||||
"entity": {
|
||||
"data": {
|
||||
"type": "users",
|
||||
"id": "user-uuid"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Responses
|
||||
|
||||
**404 Not Found** - API key does not exist
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{
|
||||
"status": "404",
|
||||
"title": "Not Found",
|
||||
"detail": "API key not found"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**409 Conflict** - API key already revoked
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{
|
||||
"status": "409",
|
||||
"title": "Already Revoked",
|
||||
"detail": "This API key has already been revoked"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Revoking an API key is permanent and cannot be undone. Any applications using this key will immediately lose access. The `revoked` field will be set to `true` and the key will no longer authenticate API requests.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
Monitor the `last_used_at` field before revoking to ensure the key is no longer in active use.
|
||||
</Tip>
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: "Update API Key"
|
||||
api: "PATCH /api/v1/api-keys/{id}"
|
||||
description: "Modify certain fields of an existing API key without affecting other settings."
|
||||
---
|
||||
|
||||
Partially update an API key's properties. This endpoint allows you to modify the name or expiration date without affecting other settings.
|
||||
|
||||
## Path Parameters
|
||||
|
||||
- `id` (required) - The UUID of the API key to update
|
||||
|
||||
## Request Body
|
||||
|
||||
The request must follow the JSON:API specification format:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"type": "api-keys",
|
||||
"id": "string",
|
||||
"attributes": {
|
||||
"name": "string",
|
||||
"expires_at": "2024-12-31T23:59:59Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Attributes
|
||||
|
||||
- `name` (optional, string) - Update the API key name (3-100 characters)
|
||||
|
||||
<Note>
|
||||
Only the `name` field can be updated. Other fields like `expires_at`, `prefix`, and `revoked` are read-only and cannot be modified after creation.
|
||||
</Note>
|
||||
|
||||
## Example Request
|
||||
|
||||
```bash
|
||||
curl -X PATCH "https://api.prowler.com/api/v1/api-keys/{id}" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/vnd.api+json" \
|
||||
-d '{
|
||||
"data": {
|
||||
"type": "api-keys",
|
||||
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
|
||||
"attributes": {
|
||||
"name": "Updated API Key Name"
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
### Success Response (200 OK)
|
||||
|
||||
Returns the updated API key with modified metadata:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"type": "api-keys",
|
||||
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
|
||||
"attributes": {
|
||||
"name": "Updated API Key Name",
|
||||
"prefix": "pk_live_abc123",
|
||||
"expires_at": "2025-12-31T23:59:59Z",
|
||||
"revoked": false,
|
||||
"inserted_at": "2024-01-15T10:30:00Z",
|
||||
"last_used_at": "2024-01-20T14:22:00Z"
|
||||
},
|
||||
"relationships": {
|
||||
"entity": {
|
||||
"data": {
|
||||
"type": "users",
|
||||
"id": "user-uuid"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
The full API key value is never returned in responses after creation. Only the prefix is shown for identification.
|
||||
</Warning>
|
||||
Reference in New Issue
Block a user