Environments & API
Exact release coordinates, public routes and failure semantics. Keep these values in trusted backend configuration.
Dev environment
Section titled “Dev environment”| Setting | Value |
|---|---|
| OIDC issuer | https://jarvis-id-dev.k8s1.aviproduction.org |
| Discovery | Issuer + /.well-known/openid-configuration |
| Personal API base | https://jarvis-api-dev.k8s1.aviproduction.org/external/v1 |
| API audience | jarvis-personal-api |
| Identity scope | openid |
| OAuth flow | Authorization code + PKCE S256 |
| Token endpoint authentication | client_secret_basic — backend only |
| Context purpose | job_application |
Owner interfaces: edit personal context and manage permissions / audit. These require owner authentication; their cookies do not authenticate the external API.
The independent dev reference uses two synthetic clients to exercise isolation. Do not use its clients or temporary domain as your product registration. Production endpoints are not declared by this guide.
Public routes
Section titled “Public routes”All paths below are relative to the personal API base. Except for public signing keys, requests require the authenticated user’s backend-held access token. The ID token is not a personal API bearer token.
| Method | Path | SDK operation |
|---|---|---|
| POST | /consent-requests |
Create separate consent |
| GET | /consent-requests/{id} |
Read authoritative decision |
| GET | /grants |
List the current app/user’s grants |
| DELETE | /grants/{id} |
Revoke a grant |
| POST | /context-packages |
Authorize, audit and disclose |
| GET | /context-signing-keys |
Read trusted Ed25519 verification keys |
The public boundary is HTTPS, not internal gRPC. Do not import generated internal service clients, call Hydra admin, or pass a Jarvis service key.
Errors and retries
Section titled “Errors and retries”| Result | Required response |
|---|---|
| 400 | Correct the request; no blind retry. |
| 401 | Reauthenticate; do not substitute an owner cookie. |
| 403 | Stop. Do not reuse a previous context package. |
| 404 | Treat the resource as unavailable; do not infer cross-user existence. |
| 409 | Resolve stale/expired/conflicting work deliberately before a new operation. |
| 429 / 503 | Surface temporary unavailability; no stale fallback or automatic disclosure. |
| Invalid signature / binding | Reject the package completely. |
Go exposes personal.Error.Status and .Code; TypeScript exposes
PersonalAPIError.status and .code. Error bodies use error.code as the stable
identifier. Neither client silently retries or turns cached data into permission.
An exact retry uses the same persisted work-unit ID and request. It can return the same immutable package with a fresh disclosure receipt while authorization remains valid. Changing facts or permission does not become safe by retrying.
Release coordinates
Section titled “Release coordinates”| Artifact | Version / source |
|---|---|
| Go module | gitlab.com/jarvis-ecosystem/jarvisapis/sdk/go@v0.2.0-alpha.1 |
| npm package | @jarvis/sdk@0.2.0-alpha.1 |
| Go tag | sdk/go/v0.2.0-alpha.1 |
| TypeScript tag | sdk/typescript/v0.2.0-alpha.1 |
| Contract | external-personal-v1.json |
| Package schema | jarvis.personal-context.v1 |
Both release tags point to 043876df8bd86dfb4f0254ea5ab8ca0eebfa1a63.
Pin the alpha version explicitly and rerun conformance checks before upgrading.
The desktop app and SDK have independent version numbers.
Canonical sources
Section titled “Canonical sources”These links require access to the private GitLab group: