Auth API¶

Soulacy supports shared API-key authentication and short-lived JWT access tokens. All protected requests use the standard bearer header:

Authorization: Bearer <api-key-or-access-token>

Exchange the server key for JWTs¶

This endpoint is available when auth.mode: jwt is enabled. It exchanges the configured static server API key for an access/refresh pair.

POST /api/v1/auth/token
Content-Type: application/json

{
  "api_key": "sy_your-server-key"
}

{
  "access_token": "eyJ...",
  "refresh_token": "opaque-refresh-token",
  "expires_in": 900,
  "token_type": "Bearer"
}

Refresh tokens are single-use: a successful refresh rotates the refresh token and returns a replacement alongside the new access token.

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "opaque-refresh-token"
}

GET /api/v1/auth/me
Authorization: Bearer <token>

The response includes the authentication mode, subject and role. JWT identities may also include email, iat, and exp.

Managed keys use the sk_ prefix. Creating and managing them requires config administration permission.

POST /api/v1/admin/api-keys
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "ci-bot",
  "scopes": ["read", "write"]
}

The 201 Created response contains the key record and a plaintext key. Save that value immediately; list operations never return it again.

GET /api/v1/admin/api-keys
Authorization: Bearer <admin-token>

Pass ?include_revoked=true to include revoked records.

DELETE /api/v1/admin/api-keys/{id}
Authorization: Bearer <admin-token>

Successful revocation returns:

{
  "status": "revoked",
  "id": "<id>"
}

Do not expose validation endpoints

API-key management routes are administrative surfaces. Keep them behind Soulacy authentication and a trusted network boundary.