Repository navigation
feat(api): API tokens v2 (personal + service accounts, scopes) and the /v1 versioned API (E1.3) - #332
Open
hoangsnowy wants to merge 5 commits into
Open
hoangsnowy wants to merge 5 commits into
hoangsnowy wants to merge 5 commits into
Conversation
…e /v1 versioned API (E1.3) API tokens - Personal tokens for every member (act as their owner) and service accounts for admins; scopes read / run / admin, closed upwards, enforced per HTTP method by ApiTokenScopeMiddleware and by the role claim (admin scope => admin role, never platform-admin). - Stored as HMAC-SHA256 with a per-token random salt, compared in constant time; legacy unsalted rows still validate. Migration AddApiTokenScopesAndSalt backfills scopes from the old role. - Expiry capped by the platform setting Tenants:ApiTokens:MaxLifetimeDays (default 366). Create / revoke / use / refusal audited (use + refusal at most once per token per 5 minutes, with IP + user agent). Member removal revokes the member's personal tokens before deleting the account. - Self-contained registration: AddApiTokenAuthentication<TPrimaryOptions>() chains the JWT forward selector; UseApiTokenScopes(). No default-scheme or policy changes. - Settings > API tokens opens to every member (personal tokens); admins also create service accounts and see / revoke every token. /tenants/me reports the auth method and scopes. /v1 - Every module REST route is served under /v1 and at its unversioned path, which is deprecated (Deprecation / Sunset / Link successor-version headers, sunset 2027-05-03) and left out of OpenAPI. SignalR hubs (IProtocolEndpointModule), /mcp and the probes stay unversioned. - OpenAPI document v1 with title, bearer scheme and policy; committed as docs/api/openapi-v1.json and kept in sync by a test. - docs/API.md: versions, auth, scopes, CI example, deprecation policy. VS Code extension: Set / Check / Clear API token (SecretStorage) and Run the pipeline via POST /v1/pipeline. Tests: token lifecycle, scopes, salting, max lifetime, audit, claims; integration on the real Api host (WebApplicationFactory): token auth next to JWT, scope per method, admin route, revoked / expired -> 401, /v1 + deprecated twins with headers, unique endpoint names, hub unversioned, OpenAPI = committed copy. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016Twi9jFk8LiG81JBRi6Ddh
…-select) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016Twi9jFk8LiG81JBRi6Ddh
hoangsnowy
marked this pull request as ready for review
November 3, 2026 15:48
…/e1-3-api-tokens Docs conflicts resolved keeping both sides: CHANGELOG + SECURITY bullets, migration notes, scorecard rows (RBAC row from #328, machine access + API contract from E1.3). #328 adds no Api routes (approvals are decided in the desktop), so nothing new needs a /v1 twin; its Approver policy works unchanged for JWT callers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016Twi9jFk8LiG81JBRi6Ddh
… into claude/e1-3-api-tokens Conflicts resolved keeping both sides: - ApiTokensApp: GAP-17 fail-closed tenant (no tenant claim => alert, never "default") kept on top of personal tokens for every member + scopes. - AgentOs.Tests.csproj: both Mvc.Testing (E1.3) and TestHost (#329). - CHANGELOG migration notes: #329's deploy notes + the API-token note. docs/api/openapi-v1.json regenerated: #334 adds optional tracker fields + the TrackerBinding schema to /v1/workspaces (additive only). #329's new routes (sign-out, exports, pairing) live on the Web host, not the versioned Api. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016Twi9jFk8LiG81JBRi6Ddh
…into claude/e1-3-api-tokens Kept both sides: - The API-token scheme registers alongside #331's FallbackPolicy (RequireAuthenticatedUser): a token principal is authenticated, so it passes; the explicit AllowAnonymous routes stay public on both twins (/tenants/register, /tenants/invitations/preview and their /v1 twins added to the reviewed anonymous inventory — nothing else becomes public). - #331's tenant + user limiter partitions a token principal exactly like a JWT (tenant; a personal token shares its owner's user bucket, a service account is its own user). - Tests: one Api reference with #331's ApiHost alias, one Mvc.Testing package version. - README API intro combines #331's public-route list and the /v1 + API-token wording. New tests: limiter keys for token principals == JWT; fallback policy with tokens; public routes stay public on both twins. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016Twi9jFk8LiG81JBRi6Ddh
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Change description
E1.3 from
docs/plans/enterprise-readiness.md(scorecard rows 4–5).API tokens and service accounts. Tokens built on the existing
aos_token (#212):sub= the owner's user id) and are revoked when the member is removed, before the account is deleted (GAP-04 order). Service accounts are admin-only workspace identities (sub=apitoken:<id>, nameservice:<name>).read/run/admin, closed upwards (admin includes run, run includes read).ApiTokenScopeMiddlewareenforces them per HTTP method:readcovers GET/HEAD/OPTIONS, and anything else needsrun. The role claim enforces the admin scope (admin scope ⇒adminrole, neverplatform-admin). A token without the needed scope gets a 403 problem+json response.AddApiTokenScopesAndSaltbackfills scopes from the old role.Tenants:ApiTokens:MaxLifetimeDays(aSettingDescriptor, default 366, range 1–1825, per ADR-0011; no appsettings key).apitoken.created/revoked/used/refused. Use and refusal rows are written at most once per token per 5 minutes, with IP and user agent, so a stale CI secret can't flood the trail. Every use is also logged (token id and prefix only).services.AddApiTokenAuthentication<JwtBearerOptions>(scheme)adds the scheme and chains the JWTForwardDefaultSelector, andapp.UseApiTokenScopes()adds the scope check. Neither touches the default scheme or any authorization policy./tenants/menow returnsauthMethodandscopes./v1versioned API.ModuleLoader.MapVersionedModuleEndpointsserves every module REST route under/v1and again at its unversioned path. The unversioned twin is deprecated: it answers withDeprecation: @<unix>(RFC 9745),Sunset(RFC 8594, 2027-05-03),Link: rel="successor-version"andrel="deprecation"headers. Its endpoint names are stripped (via aFinallyconvention) so names stay unique, and it is excluded from OpenAPI.IProtocolEndpointModulemarker),/mcpand the probes stay unversioned.v1(title, bearer scheme, policy) is committed asdocs/api/openapi-v1.json. A test fails when the running Api drifts from it (regenerate withAGENTOS_UPDATE_OPENAPI=1). Live/openapi/v1.jsonand Scalar stay non-Production, per the hardening checklist.docs/API.mdcovers versions, authentication, scopes, a GitHub Actions example and the deprecation policy: additive-only within a version, six months' minimum notice, CHANGELOG Deprecated / Removed entries.VS Code extension: new commands Set / Check / Clear API token (stored in VS Code SecretStorage, checked against
/v1/tenants/me) and Run the pipeline on a user story (POST /v1/pipeline), plus a newagentos.apiUrlsetting.Docs: API.md (new), CONFIG.md, SECURITY.md, hardening checklist, scorecard rows 4–5 plus the shipped table, CHANGELOG (Added / Deprecated / Migration notes), README API section, extension README, CLAUDE.md wiring sentence.
Type of change
Related issues
Enterprise readiness E1.3 (scorecard #4 Machine access, #5 API contract).
Checklist
dotnet buildpasses locally in Release mode (dotnet build AgentOs.slnx -c Release: 0 errors, on the official 10.0.402 SDK)dotnet testpasses (dotnet test --solution AgentOs.slnx -c Release: 3195 total, 0 failed, 97 skipped = the gated E2E/lab suites)Test plan
Automated (in this PR)
ApiTokenTests: format; salted HMAC vs legacy SHA-256; constant-time compare; scope normalisation and the role mapping; method → scope; create / validate / revoke / expire; legacy-row validation; the max-lifetime setting (default cap + custom cap); members can't create service accounts or the admin scope; who can list and revoke what;RevokeForOwnerAsync; the audit trail (created / used / refused / revoked, with use and refusal throttled); claims for personal vs service tokens; the forward selector.ApiV1IntegrationTestsboots the real Api host with WebApplicationFactory (Development, no DB; token store = the realApiTokenServiceon EF InMemory). It covers: token auth next to the JWT scheme; the tenant and scopes in/v1/tenants/me; a personal token acting as its owner; a read token gets 403 on POST; a run token reaches the endpoint; the admin route needs the admin scope; revoked, expired, unknown and malformed tokens get 401 withinvalid_token; no credentials gets 401; legacy routes return 200 withDeprecation/Sunset/Link(even on a 401) and/v1returns none; probes aren't deprecated;/v1endpoint names are unique, legacy twins are unnamed, and the hub is unversioned; OpenAPI documents only/v1and matches the committed copy.MemberRemovalTests: personal tokens are revoked before the Keycloak delete; a failed token revoke removes nothing.Manual, run in this session (Web + Api standalone against a local Postgres 16)
\d).GET /v1/tenants/me→ 200 (service:…, scopesread run); legacy/tenants/me→ 200 with the deprecation headers.POST /v1/requirement {}→ 400 (got past auth); on the admin route → 403.POST→ 403 Insufficient token scope.tenants.audit_eventsheld created ×2, used ×2 (with IP), revoked, refused; rows are salted (32-hex salt) and the personal row carriesOwnerUserId.Still to verify on the lab / full Aspire stack (persistence, auth and tenancy, so a standalone run isn't proof)
POST /v1/pipeline, and the run shows under the tenant.ApiTokensRealAuthTests(updated for/v1andservice:<name>) green on the full stack (RUN_AGENTOS_E2E_REAL=true).apiTokensRevoked=N)./v1/*and on the legacy routes (forward-selector chaining).Notes / follow-ups
settings-api-tokensscreen (Type and Scope selects, the workspace-wide list) still needs pushing up with/design-login→ DesignSyncwrite_files.Generated by Claude Code