Authentication and authorization

Anonymous reads

Use https://models-registry.neat.sima.ai for the public operations marked Public reads in the reference. No AWS access key, GitHub token, API key, or bearer token is required. Access remains restricted to configured public repositories, currently sima-neat/models.

Public operations include repository/branch discovery, catalog and taxonomy reads, model/run search, exact resolution, run/provenance/test/metric reads, latest benchmark/accuracy results, and artifact download-URL requests. Being a GET does not by itself make an operation public.

IAM-protected operations

Use https://artifacts-registry.neat.sima.ai and sign with AWS Signature Version 4, region us-west-2, service execute-api. All routes on this API Gateway host require IAM authentication, including the GET equivalents of public reads. The public edge uses a separate origin authentication path internally; callers do not sign requests to the public host.

Operation group	Identity / authorization
Create/finalize runs, register inputs/parameters/artifacts/tests/measurements, publish catalogs/taxonomies	Repository-scoped publisher role
GET /v1/runs/{run_id}/publication-status	Authorized publisher; not anonymous
Branch purge/restore and GET /v1/purge-jobs/{job_id}	IAM role with the corresponding route permission and repository authorization
Candidate create/read, run association, finalization, feature-branch selection, promotion request/read/cancel	Authorized repository publisher; these GETs are not anonymous
Promotion approval/rejection	Separate scoped approver role; publication permission alone cannot approve a promotion
Branch reconciliation	Dedicated reconciliation role; ordinary publication permission is insufficient
Direct metadata GETs at the IAM endpoint	IAM identity with read invocation permission; publisher roles do not automatically grant read access

GitHub Actions publishers exchange GitHub OIDC identity for short-lived AWS credentials using the configured repository role. They need id-token: write and an allowed OIDC trust subject. A GitHub token alone cannot authenticate a registry HTTP request. The writer derives repository identity from the AWS role; a request cannot choose another repository simply by changing its payload.

Signed request example

After assuming an authorized role, export AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN through your credential tooling. Use a curl build that supports --aws-sigv4. Never embed credentials in source.

export REGISTRY_WRITE=https://artifacts-registry.neat.sima.ai
RUN_ID='<run-id>'
curl --fail-with-body \
  --aws-sigv4 'aws:amz:us-west-2:execute-api' \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  --header "x-amz-security-token: $AWS_SESSION_TOKEN" \
  "$REGISTRY_WRITE/v1/runs/$RUN_ID/publication-status"

Use the session token with temporary credentials and refresh the session when it expires. SigV4 covers the method, host, path, query, headers, and payload: sign only after constructing the final request. Keep system time synchronized. The API reference displays the scheme and client examples but does not compute AWS SigV4 signatures. An Authorization header field is not a substitute for an AWS signing client. Browser request sending is disabled on this documentation site.

The downloadable OpenAPI contract supplies the public server at each anonymous operation and inherits the IAM server for protected operations. security: [] means anonymous on that operation's public server, not on every Vulcan hostname.

Production rollout permissions

Production currently allowlists sima-neat/models for anonymous reads. The configured Models publisher is enabled for production GitHub OIDC; other publishers are not enabled by the module-wide default. Promotion approver roles are not yet configured, and background mutations are disabled. The reference includes these API contracts, but using a protected operation still requires an enabled identity and its specific permissions. Coordinate onboarding with the Vulcan operator rather than assuming every documented workflow is enabled.