AimableDocs
DocsAPI Reference

Secrets

Secrets Management in FastAPI

In FastAPI, the "secrets" domain is designed to securely manage sensitive information such as API keys, passwords, and other confidential data. This functionality is crucial for maintaining the integrity and security of applications by ensuring that sensitive data is stored and accessed in a controlled manner.

Key Concepts

  • Secrets: These are pieces of sensitive information that need to be securely stored and managed. They can include API keys, tokens, passwords, and other confidential data.
  • Idempotency: This is a key concept when creating secrets, ensuring that multiple identical requests have the same effect as a single request. This is managed via the Idempotency-Key header.
  • Pagination: When listing secrets, pagination is supported through the limit and cursor query parameters, allowing you to control the number of results returned and navigate through large sets of data.
  • Authentication: Access to the secrets endpoints can be controlled using the X-API-Key header, which should be included in requests to authenticate and authorize access.

Common Workflows

Listing Secrets

To retrieve a list of secrets, you can use the GET /v1/admin/secrets endpoint. This endpoint supports pagination and filtering by provider slug.

curl -X GET "https://api.example.com/v1/admin/secrets?limit=10&provider_slug=aws" \
-H "X-API-Key: your_api_key"

Creating a Secret

To create a new secret, use the POST /v1/admin/secrets endpoint. Ensure that you include the Idempotency-Key header to prevent duplicate secret creation.

curl -X POST "https://api.example.com/v1/admin/secrets" \
-H "Idempotency-Key: unique_key" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{"name": "my_secret", "value": "super_secret_value"}'

Retrieving a Secret

To get the details of a specific secret, use the GET /v1/admin/secrets/{secret_id} endpoint by providing the secret's unique identifier.

curl -X GET "https://api.example.com/v1/admin/secrets/12345" \
-H "X-API-Key: your_api_key"

Updating a Secret

To update an existing secret, use the PATCH /v1/admin/secrets/{secret_id} endpoint. This allows you to modify the secret's details.

curl -X PATCH "https://api.example.com/v1/admin/secrets/12345" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{"value": "new_secret_value"}'

Deleting a Secret

To delete a secret, use the DELETE /v1/admin/secrets/{secret_id} endpoint. This action is irreversible, so ensure that the secret is no longer needed before deletion.

curl -X DELETE "https://api.example.com/v1/admin/secrets/12345" \
-H "X-API-Key: your_api_key"

Important Considerations

  • Authentication: Always include the X-API-Key header in your requests to authenticate and authorize your access to the secrets endpoints.
  • Idempotency: Use the Idempotency-Key header when creating secrets to ensure that retries do not result in duplicate entries.
  • Error Handling: Be prepared to handle errors such as unauthorized access (HTTP 401), not found (HTTP 404), and validation errors (HTTP 400). Proper error handling will improve the robustness of your application.
  • Security: Ensure that your API key and secrets are kept secure and not exposed in client-side code or logs.

By following these guidelines and utilizing the secrets management endpoints effectively, you can securely manage sensitive information within your FastAPI applications.