API Reference

This document provides a comprehensive reference for the Qalá API, detailing the available endpoints and functionality for secure secret management.

Base URL

All API requests should be made to: https://api.qala-security.com

Authentication

Qalá API uses JWT token-based authentication. You can authenticate using either:

Login with Email and Password

POST /auth/login

Request Body:

{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

{
  "token": "your-jwt-token"
}

Login with API Key

POST /auth/token

Request Body:

{
  "apiKey": "your-api-key"
}

Response:

{
  "token": "your-jwt-token"
}

Once authenticated, include the JWT token in the Authorization header for all subsequent requests:

Authorization: Bearer your-jwt-token

User Endpoints

Get User Profile

GET /user/profile

Response:

{
  "id": "user-id",
  "email": "user-email",
  "name": "user-name",
  "projects": [
    {
      "id": "project-id",
      "name": "project-name"
    }
  ]
}

Project Endpoints

List Projects

GET /projects

Response:

[
  {
    "id": "project-id",
    "name": "project-name",
    "description": "project-description"
  }
]

Create Project

POST /projects

Request Body:

{
  "name": "project-name",
  "description": "project-description"
}

Response:

{
  "id": "project-id",
  "name": "project-name",
  "description": "project-description"
}

Get Project Details

GET /projects/:projectId

Response:

{
  "id": "project-id",
  "name": "project-name",
  "description": "project-description",
  "createdAt": "timestamp"
}

Environment Endpoints

List Environments

GET /projects/:projectId/environments

Response:

[
  {
    "name": "environment-name"
  }
]

Create Environment

POST /projects/:projectId/environments

Request Body:

{
  "name": "environment-name"
}

Response:

{
  "name": "environment-name"
}

Secret Management Endpoints

List Secrets

GET /projects/:projectId/environments/:environment/secrets

Response:

[
  {
    "name": "secret-name",
    "description": "secret-description",
    "updatedAt": "timestamp"
  }
]

Get Secret

GET /projects/:projectId/environments/:environment/secrets/:secretName

Response:

{
  "name": "secret-name",
  "value": "secret-value",
  "description": "secret-description",
  "updatedAt": "timestamp"
}

Create or Update Secret

PUT /projects/:projectId/environments/:environment/secrets/:secretName

Request Body:

{
  "value": "secret-value",
  "description": "secret-description"
}

Response:

{
  "name": "secret-name",
  "description": "secret-description",
  "updatedAt": "timestamp"
}

Delete Secret

DELETE /projects/:projectId/environments/:environment/secrets/:secretName

Response:

204 No Content

Rotate Secret

POST /projects/:projectId/environments/:environment/secrets/:secretName/rotate

Response:

{
  "name": "secret-name",
  "description": "secret-description",
  "updatedAt": "timestamp"
}

Logging

Log Secret Access

POST /projects/:projectId/logs

Request Body:

{
  "environment": "environment-name",
  "secretName": "secret-name",
  "action": "read", // or "write", "delete", etc.
  "timestamp": "ISO-timestamp"
}

Response:

200 OK

Error Handling

The API returns standard HTTP status codes to indicate success or failure:

• 200 OK: Request was successful
• 201 Created: Resource was successfully created
• 204 No Content: Request succeeded with no response body
• 400 Bad Request: Request was malformed or invalid
• 401 Unauthorized: Authentication failed
• 403 Forbidden: Authenticated user doesn't have permission
• 404 Not Found: Requested resource not found
• 500 Internal Server Error: Server encountered an error

Error responses include a message field:

{
  "message": "Error description"
}

Rate Limits

API requests are subject to rate limiting to ensure service stability. The current limits are:

• 100 requests per minute per IP address
• 1000 requests per hour per authenticated user

When a rate limit is exceeded, the API returns a 429 Too Many Requests status code.