AimableDocs
DocsAPI Reference

Secrets

Secrets Management

The Secrets domain in the Aimable Platform API (v0.1.0) enables secure storage, retrieval, and management of sensitive values such as API keys, passwords, and tokens. These secrets are encrypted at rest and never exposed in plaintext through read operations — only metadata is returned. This ensures that credentials remain protected while still allowing automation and integration workflows to reference them safely.

Key Concepts

  • Secret: A securely stored value associated with a name, type, and provider. The actual value is encrypted and inaccessible via API responses.
  • secret_type: Categorizes the secret (e.g., api_key, password, token).
  • provider_slug: Identifies the target service or provider (e.g., aws, github, slack).
  • Idempotency-Key: Required header when creating secrets to prevent duplicate creation on retries.
  • All operations return metadata only — never the plaintext or encrypted value.

Authentication is required for all endpoints using either a Bearer token (Authorization: Bearer <token>) or an X-API-Key header.

Common Workflows

1. Create and Manage a Secret

Create a Secret

Use POST /v1/admin/secrets to store a new secret.

curl -X POST 'https://api.aimable.com/api-proxy/v1/admin/secrets' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Idempotency-Key: abc123-xyz' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "github_webhook_token",
    "secret_type": "token",
    "provider_slug": "github",
    "value": "ghp_abcdef1234567890"
  }'

Response (201 Created):

{
  "data": {
    "id": "sec-9f8e7d6c5b4a3b2a",
    "tenant_id": "ten-8a7b6c5d4e3f2g1h",
    "name": "github_webhook_token",
    "secret_type": "token",
    "provider_slug": "github",
    "created_at": "2025-04-05T10:00:00Z",
    "updated_at": "2025-04-05T10:00:00Z"
  }
}

✅ The Idempotency-Key ensures you won't accidentally create duplicates if the request is retried.

Retrieve a Secret's Metadata

Use GET /v1/admin/secrets/{secret_id} to get metadata about a secret.

curl -X GET 'https://api.aimable.com/api-proxy/v1/admin/secrets/sec-9f8e7d6c5b4a3b2a' \
  -H 'Authorization: Bearer <your-access-token>'

Response (200 OK):

{
  "data": {
    "id": "sec-9f8e7d6c5b4a3b2a",
    "tenant_id": "ten-8a7b6c5d4e3f2g1h",
    "name": "github_webhook_token",
    "secret_type": "token",
    "provider_slug": "github",
    "created_at": "2025-04-05T10:00:00Z",
    "updated_at": "2025-04-05T10:00:00Z"
  }
}

🔐 Note: The actual secret value is never included in responses.

Update a Secret

You can update the name or rotate the value using PATCH.

curl -X PATCH 'https://api.aimable.com/api-proxy/v1/admin/secrets/sec-9f8e7d6c5b4a3b2a' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "github_webhook_token_v2",
    "value": "ghp_newtoken1234567890"
  }'

Response (200 OK): Returns updated metadata with new updated_at timestamp.

Delete a Secret

Soft-delete a secret by ID.

curl -X DELETE 'https://api.aimable.com/api-proxy/v1/admin/secrets/sec-9f8e7d6c5b4a3b2a' \
  -H 'Authorization: Bearer <your-access-token>'

Response (200 OK): Includes the deleted_at field in the returned metadata.

2. List Secrets with Pagination

Retrieve all secrets, optionally filtered by provider.

curl -X GET 'https://api.aimable.com/api-proxy/v1/admin/secrets?provider_slug=github&limit=5' \
  -H 'Authorization: Bearer <your-access-token>'

Response (200 OK):

{
  "data": [
    {
      "id": "sec-9f8e7d6c5b4a3b2a",
      "name": "github_webhook_token_v2",
      "secret_type": "token",
      "provider_slug": "github",
      "created_at": "2025-04-05T10:00:00Z",
      "updated_at": "2025-04-06T14:20:00Z"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "cursor_12345"
  }
}

Use cursor in subsequent requests:

?cursor=cursor_12345&limit=5

Authentication & Error Handling

All endpoints require authentication:

  • Use Authorization: Bearer <token> or
  • Use X-API-Key: <key>

Common Errors

| Status | Meaning | |-------|--------| | 401 | Missing or invalid authentication | | 403 | Insufficient permissions | | 422 | Invalid input (e.g., missing Idempotency-Key, malformed UUID) |

Example 422 response:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Best Practices

  • Always use unique Idempotency-Key values when creating secrets.
  • Rotate secrets regularly using PATCH /secrets/{id} with a new value.
  • Use provider_slug and secret_type to organize and filter secrets programmatically.

With this API, you can automate secure credential management without ever exposing sensitive data in logs or responses.

Related Endpoints