Return the authenticated principal's profile (account details + email verification status). Works for both human and service principals.

Patch the authenticated user's profile. Omitted fields are left untouched. model_config and capabilities apply to service accounts only.

Change the authenticated user's password. Verifies the current password, then revokes every active session except the one making this request (so the user isn't logged out of the tab they're sitting in). Service accounts cannot call this — they have no password. Rate limit: 5 / minute / IP.

List every active session for the authenticated user. The session backing the current request is flagged with is_current: true. Also available at /api/v1/sessions (legacy path).

Revoke a specific session by id. The user can revoke any of their own sessions, including the current one (which terminates the calling session). Also available at /api/v1/sessions/{session_id}.

Audit-log entries where the authenticated user is the actor. Paged. The actor_id filter is forced server-side to the calling user, so callers cannot pivot to another user's feed.

Action vocabulary (dot-notation, used in action filter and action field of returned items):

• account.profile_updated, account.accessed
• auth.login, auth.login_failed, auth.logout,

auth.token_refreshed, auth.password_changed, auth.password_reset

• member.invited, member.removed
• invitation.cancelled
• service_account.archived, service_account.paused,

service_account.resumed

• api_key.created, api_key.revoked

New actions may be added without a docs revision; consumers should tolerate unknown values (display as-is, don't reject).

Create a new human account. A personal organization is created in the same transaction with the registrant as owner. A verification email is queued (event email.requested). Auto-logs in: returns access + refresh tokens and sets the SSO refresh cookie. Rate limit: 3 / minute / IP.

Authenticate with email + password. Returns access + refresh tokens and the user's full organization list. Sets refresh + CSRF cookies. Brute-force protection: per-IP and per-account counters with progressive delay and lockout. Rate limit: 5 / minute / IP.

Exchange a refresh token for a new access + refresh pair. The old refresh token's hash is rotated server-side; the old JTI is added to the revocation list once rotation is persisted. Replaying the old refresh token after this call kills the session (reuse detection). Refresh token may be in the body or in the refresh_token cookie (SSO flow).

Revoke the current session. The access token's JTI is also added to the revocation list so a token stolen before logout stops validating immediately. Cookies are always cleared on the response, even if the server-side revoke fails. Service principals cannot call this endpoint — they have no session.

Revoke every active session for the calling account. Useful for "I lost my phone" or post-password-change cleanups. Cookies are rotated/cleared on the response.

Re-emit the verification email for an unverified account. Always returns success regardless of whether the email exists, to avoid leaking account presence. Rate limit: 3 / minute / IP.

Initiate a password reset. Always returns success, even when the email is unknown, to prevent email enumeration. Generates a 1-hour JWT and emits an email.requested event with the reset link.

Complete a password reset using the JWT from the email link. Validates the token (signature + jti not previously used), updates the password hash, and revokes all sessions for the account.

Introspect an access token (signature + exp + revocation). Used by downstream services that prefer a server-side check over local public-key verification. Returns the claims as-is: permissions come from the token, not re-derived from current state. Use /auth/refresh if you need fresh permissions. Rate limit: 100 / minute / IP.

Return the principal identity carried by the request — exactly what the middleware extracted, with no extra DB lookups. Useful for SDKs and gateways debugging auth wiring.

Return the RS256 public key (PEM) for local JWT verification by downstream services. Cache this for the lifetime of expires_at (default 90 days).

Key rotation strategy:

• Each issued JWT carries a kid claim in its header naming the

key that signed it (e.g. key-2026-03-01-v1).

• Verifiers should cache by kid. On a cache miss (unfamiliar

kid), re-fetch this endpoint to learn the new key.

• During rotation, account-service serves the new key here

but continues to accept tokens signed by the previous key until those tokens naturally exp. Verifiers should retain the previous key entry until its tokens have aged out.

• expires_at is the rough cache horizon — refresh before that

even without a kid mismatch to pick up scheduled rotations.

Validate the supplied X-API-Key header and return a 1-hour service JWT (principal_type: service). Lets a service principal authenticate downstream calls with a verifiable JWT instead of re-presenting the API key on every hop. The JWT carries the service account's capabilities as permissions and nil as sid.

Lightweight liveness check. Returns 200 with a small JSON when the process is up. Does not touch DB / Redis / RabbitMQ — use /health/detailed for that. Suitable for k8s livenessProbe.

Per-dependency health snapshot. Probes Postgres, Redis, and RabbitMQ and returns each dependency's state. A degraded dependency yields HTTP 503 so a load balancer can drop the pod from rotation. Heavier than /health — call from readinessProbe, not livenessProbe.

Prometheus exposition format. Includes HTTP request counters / latency histograms (sanitized path labels — id segments collapsed to :id so cardinality stays bounded), gRPC counters, brute-force counters, rate-limiter counters, and Redis connection pool stats. Should be firewalled to the metrics-collector subnet, not exposed publicly.

Lightweight existence + display info for an organization. Used by frontends to validate org-scoped invitation links before login. Returns minimal data — no member or role info is leaked.

List organizations the authenticated principal is a member of. Each entry includes the principal's role in that org.

Create a new organization with the caller as owner. Slug is auto-derived from the name when omitted; if the slug collides a 4xx is returned and the caller should retry with an explicit slug.

Fetch a single organization by id. Caller must be a member.

Update the organization's name or slug.

Soft-delete (archive) an organization. Owner-only — protected by the owner role's * wildcard rather than a per-action permission. Members lose access on next token rotation; all sessions remain intact for other orgs the user belongs to.

Issue a new token pair bound to a different organization. The existing session id is reused, so refresh continuity is preserved. The caller must already be a member of the target org.

Remove the caller's own membership. Owners cannot leave — transfer ownership first or delete the organization.

Paged member list with role + permissions.

Send an invitation to an email address. If a role is omitted the org's default-member role is assigned on accept. The recipient gets an email via the email.requested event.

Remove a member from the org. Cannot remove the owner.

Reassign a member to a different role. New role takes effect on their next token rotation.

List roles defined in the org (system + custom).

Create a custom role. Permissions are free-form strings (the permission service interprets them); see the Permissions section for the canonical names used by account-service itself.

Fetch a single role.

Patch a role. System roles (e.g. owner) are read-only.

Delete a custom role. Fails if any member is currently assigned to it — reassign them first. System roles cannot be deleted.

Org-wide audit feed. Same shape as /me/activities but scoped to all actors within the organization. Requires audit_logs:read permission in the org.

List service accounts in an organization. The org is supplied as a query parameter (not a path segment) because callers commonly enumerate across orgs they manage.

Create a new service account scoped to an organization. The returned account has no API key yet — call POST /service-accounts/{account_id}/api-keys afterwards.

Fetch one service account by id.

Patch metadata, capabilities, or rate limit. Permission changes take effect on the next /auth/token-exchange call (or immediately for raw X-API-Key flows).

Soft-delete (archive) a service account. All of its API keys are revoked. Existing service JWTs continue to validate until their natural exp (max 1 hour); add the JTI to the revocation list via re-issued tokens to shorten that further.

Temporarily disable a service account. API keys stop authenticating until resumed; metadata and capabilities are preserved.

Re-enable a paused service account.

List metadata for every key on a service account. The plaintext is never returned here — only key_prefix for identification.

Mint a new API key. The key field in the response is the only time the plaintext is ever exposed — store it client-side immediately. Subsequent calls see only the hash and key_prefix.

Mark a key as revoked. The key continues to exist for audit purposes but stops authenticating immediately.

Permanently remove a key (hard delete). Prefer revoke for auditable history.

Creates a folder owned by the caller. If parent_id is provided, the folder is nested under that parent and inherits a depth of parent.depth + 1. The DB enforces sibling-name uniqueness — duplicates return HTTP 409.

Lists folders owned by the caller. Default scope is the current parent's children (or roots when parent_id is omitted). Set recursive=true to flatten the entire subtree.

Renames a folder. The DB trigger trg_update_folder_path rewrites every descendant's path inside the same transaction. Root folders cannot be renamed.

Returns the immediate children: subfolders and media files in a single paginated response. Useful for a Drive-style file browser UI.

Deletes the folder. The non-force path requires the folder to be empty (no media, no subfolders) and returns HTTP 412 if it is not. With force=true the entire subtree is purged: for every media in the subtree, all derived variant blobs (medium /high/low) are removed first, then the original blob, then the media row; finally the folder rows cascade. Variant cleanup failures are logged but never abort the purge — same reasoning as the single-media delete endpoint.

Returns a static JSON payload indicating the service process is up. Does not check downstream dependencies (DB, storage).

Paginated listing. Supports filtering by folder, visibility, file type, and a search term applied to original_name. The search input is parameterised at the SQL layer.

Streams the media bytes back with the original Content-Type and Content-Disposition. Visibility rules apply: public is unauthenticated, organization requires same-org JWT, private requires the owner's JWT.

Variant selection (?variant=) — for image uploads, the service stores the original plus optional re-encoded variants at decreasing quality. Use the query param to pick which one to download:

original (default) — uncompressed bytes, format as uploaded. SHA-256 matches the upload-time checksum. high (q=90) — light recompression, near-original quality. medium (q=75) — balanced; suitable for previews. low (q=50) — aggressive; suitable for thumbnails.

Aliases also accepted: orig / raw for original, hi for high, med for medium, lo for low. Invalid values return HTTP 400 with the allowed list.

The medium variant is generated eagerly on upload (when IMAGE_EAGER_MEDIUM=true); other levels are generated lazily on first request and cached for subsequent ones. Generation is best-effort — if the original cannot be re-encoded (corrupt image, unsupported format), the request fails with HTTP 500 rather than silently returning the original.

The Content-Disposition filename is always the upload's display name regardless of variant — the tier is invisible to the user-facing UI.

Range / streaming (video only) — when the underlying MIME is video/*, the response includes Accept-Ranges: bytes and the endpoint honours Range: request headers. This lets the browser's HTML5 <video> element scrub mid-file without downloading from byte 0. Supported forms:

Range: bytes=N-M → 206 Partial Content Range: bytes=N- → 206 from N to EOF Range: bytes=-M → 206 last M bytes Multi-range / unparseable → ignored, full 200 returned Out-of-bounds → 416 with Content-Range: bytes /<total>

Non-video MIMEs do NOT advertise Accept-Ranges and ignore any Range: header — they always stream the full body.

Returns the metadata only (no bytes). Useful for clients that want size/MIME/checksum without paying for the download.

Updates the user-facing original_name. The on-disk filename is unchanged; only the display name is rewritten.

Switches the media row's visibility level. Does not propagate to shared links; existing tokens keep working until they expire or are deleted.

Removes every blob (original + each derived variant) from storage, then deletes the media row. The matching media_variants rows go away via FK cascade. A StorageError::NotFound is tolerated per file so retries on a partially-failed delete are idempotent.

A failure cleaning a single variant blob is logged but does not abort the delete — the user's media still goes away; worst case is one orphan blob on disk. Operators can sweep orphans by walking the storage directory and reconciling against media_variants.storage_path.

Returns the caller's most recently accessed media, newest-first. Capped at the value the client requests (default applied server-side).

Records an access event for the given media. Idempotent at the row level — repeated tracks update the existing row's timestamp instead of inserting duplicates.

Wipes the caller's entire recent-files history. The underlying media files are untouched.

Mints a shared-link token for the given media. The caller must own the media or have download access through it. Visibility defaults to restricted (creator-only) — set public for anonymous access or organization to gate by the caller's org.

Anonymous (or authenticated, for restricted/organization links) entry point. Streams the media bytes back. The download counter is incremented atomically.

Failure modes (401/403/404): link not found / revoked → 404 expired → 410 download cap reached → 429 password missing/wrong → 401 * caller not eligible for restricted / organization → 403

Lists shared links the caller created. Paginated.

Revokes a shared link. Subsequent GET /share/:token requests return 404. The underlying media file is unaffected.

Lists the caller's starred media in reverse-chronological order (most recently starred first). Each item includes the underlying media metadata plus starred_at and notes.

Stars (or re-stars) a media file. Optional notes are stored alongside the star. Calling this on an already-starred file is a no-error update.

Removes the star. Idempotent — unstarring an already-unstarred file returns success.

Convenience endpoint that flips the star state. Useful for UIs that bind a single button to "star/unstar" without tracking current state client-side.

Bulk lookup: given a list of media IDs, returns which ones the caller has starred. Lets a list view annotate every row in one round-trip.

Streams a single multipart file part (field name file) into storage. The response carries the canonical media metadata, including the SHA-256 checksum and the storage path of the original bytes.

Validation order: filename → MIME allow/block → quota fast-path → stream to disk (max-size enforced authoritatively) → magic-byte sniff → rebuild against policy → DB row.

Original is never overwritten. For images, the upload pipeline additionally generates the medium variant (quality 75) post-DB-save when IMAGE_EAGER_MEDIUM=true. high (90) and low (50) are generated lazily on first GET /media/{id}?variant=…. Variant generation is best-effort — failure here logs a warning but the upload itself succeeds with the original committed.

On any post-stream failure the staged blob is removed; the invariant "DB row ⇒ storage file exists" is preserved.

Membuat satu notifikasi dengan satu atau banyak recipient. Akan dipush ke provider sesuai provider_type (email/telegram/whatsapp/http/grpc/rabbitmq).

Kirim banyak notifikasi sekaligus dengan batch_id tunggal.

Fetch detail satu notifikasi berdasarkan ID.

Paginated history dengan filter optional (status, provider_type, date_from, date_to).