Skip to content

docs(adr): amend ADR-005 — the API also accepts Ory access tokens - #254

Draft
alukach wants to merge 2 commits into
mainfrom
docs/adr-005-ory-access-tokens
Draft

alukach wants to merge 2 commits into
mainfrom
docs/adr-005-ory-access-tokens

Conversation

@alukach

@alukach alukach commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Adds an amendment note to ADR-005. The source.coop API now accepts Ory access tokens from source-coop login as well as the proxy's assertions, verified with the same pins and routed by iss. Nothing the proxy signs or decides changes. Proxy assertions stay read-only (the API refuses them for writes); Ory tokens may also write; service accounts still reach the API through the proxy.

Merge alongside source-cooperative/source.coop#654 (step 3 of the runbook in source-cooperative/source-coop-cli#23).

Related

🤖 Generated with Claude Code

https://claude.ai/code/session_017poyHYEyxWEJct9X8Q71qF

The API now takes an Ory access token from `source-coop login` as a bearer, alongside the proxy's assertions. The proxy's side of ADR-005 is unchanged; the amendment records that it is no longer the only signer the API trusts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017poyHYEyxWEJct9X8Q71qF
@claude

claude Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @alukach's task in 10s —— View job


✅ No blocking issues — safe to merge.

The change is a docs-only amendment note to adrs/005-authorization.md (+3 lines). It reads consistently with the existing ADR-013 note. I couldn't check it against the source.coop API implementation, since that code isn't in this repo.

Non-blocking points:

  • The PR description still contains unfilled {{API_PR}} and {{CLI_LOGIN_PR}} placeholders. Fill them in before merging.
  • The note is dated 2026-10-13, but the PR was opened around 2026-10-09. Check that this is the intended merge or effective date.

Simplify (ponytail)

  • Nothing to cut. It's one note, and there's no code.

💰 Estimated review cost: $0.08 · 0m09s · 5 turns

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

🚀 Latest commit deployed to https://source-data-proxy-pr-254.source-coop.workers.dev

  • Date: 2026-11-20T01:41:28Z
  • Commit: a6d9a06

@alukach alukach changed the title … docs(adr): amend ADR-005 — the API also accepts Ory access tokens Oct 9, 2026
alukach added a commit to source-cooperative/source.coop that referenced this pull request Oct 13, 2026
Part of #588. The CLI half is source-cooperative/source-coop-cli#23.

The API now takes an Ory access token as a bearer, alongside the
assertions the data proxy signs, so the CLI can call `/api/v1` as the
person who logged in. `getApiSession` routes a bearer by its unverified
`iss`: Ory's tokens go to the new `authenticateWithOryAccessToken`, and
the proxy's go to the existing verifier. Neither falls back to the other
or to the session cookie.

The Ory verifier checks the token against Ory's published JWKS, with the
issuer (with or without a trailing slash), RS256, expiry, a 30-second
tolerance, and the request's origin as audience. An ID token, which Ory
issues to the client ID, never passes, and which clients may mint a
token for the API is decided in Ory by the audiences each client is
allowed. The subject is looked up only as a person's Ory identity. Both
verifiers build the session in one place, `sessionForAccount`. The
issuer is `NEXT_PUBLIC_ORY_SDK_URL`, which is each Ory project's issuer
domain.

**Deploying:**

The CLI's Ory clients need the `jwt` access-token strategy and this
site's origin as an allowed audience. Until a client has both, the API
answers that environment's Ory tokens with 401. Nothing else breaks:
only newer CLI builds send Ory tokens, so merging first is safe.

| | Staging client (`a79c9537…`) | Production client (`197e20e7…`) |
|---|---|---|
| Allowed audience | `https://staging.source.coop` ✅ |
`https://source.coop` ✅ |
| `access_token_strategy: jwt` | ✅ set 2026-10-13 | ✅ set 2026-10-13 |

**Changing a client** (done for both; kept for reference and rollback):
`ory patch oauth2-client` doesn't exist, and `ory update oauth2-client`
replaces the whole client. So export the client, change one field, and
send the whole thing back:

```bash
P=d567800d-b705-49d1-8a28-6f92f3a4c053 C=197e20e7-d52d-4d1d-9e54-4b73a342034b
ory get oauth2-client $C --project $P --format json > prod-cli-client.before.json
jq '.access_token_strategy = "jwt"' prod-cli-client.before.json > prod-cli-client.jwt.json
ory update oauth2-client $C --project $P --file prod-cli-client.jwt.json
ory get oauth2-client $C --project $P --format json | jq .access_token_strategy   # "jwt"
```

Rollback: `ory update oauth2-client $C --project $P --file
prod-cli-client.before.json`.

- **No Vercel changes.** Each deployment's `NEXT_PUBLIC_ORY_SDK_URL` is
already the issuer in its tokens: `https://auth.staging.source.coop` on
staging and previews (checked against a real staging token),
`https://auth.source.coop` on production. A local API can't accept CLI
tokens at all, since no CLI client allows a localhost audience.
- Merging deploys staging. Check with a staging CLI build: `source-coop
login`, then `source-coop api whoami --api-url
https://staging.source.coop` should return your account, and `creds`
with `aws s3 ls` should still work.
- The next release deploys production. Repeat the checks against
`https://source.coop`. The release ships everything on `main`: if #651
is in it, data.source.coop#253 must be deployed first.
- Rollback is a revert: only Ory-token calls are affected.

**Docs:**

- **ADR-005:** amended in source-cooperative/data.source.coop#254. It
said the API authenticates proxy-signed tokens; it now records the
second signer.
- **OpenAPI:** the `bearerAuth` description names `source-coop login`
and `source-coop auth token`.
- **`public/llms.txt`:** checked. Its line ("a token from the CLI's
login or a service account") still holds.
- **docs.source.coop:** checked. No page describes calling the API with
a token yet.

## Testing

- `npm run type-check` passes.
- `npx jest src/app/api src/lib`: 535 passed across 53 suites, including
new suites for the Ory verifier and for `getApiSession`'s routing.
- `next lint` on the changed files reports nothing.
- Against real Ory (staging, 2026-10-13): after the CLI client was
switched to `jwt`, a `source-coop login` token was an RS256 JWT with
`iss` `https://auth.staging.source.coop` and `aud`
`["https://staging.source.coop"]`, and empty `ext`. That matches what
the verifier checks. The API call itself (`source-coop api whoami`
against staging) waits for this to deploy, since a preview's origin
isn't an allowed audience.

## Related

- CLI login session, which sends these tokens:
source-cooperative/source-coop-cli#23
- CLI product commands: source-cooperative/source-coop-cli#24
- ADR-005 amendment: source-cooperative/data.source.coop#254
- Deployment runbook: in source-cooperative/source-coop-cli#23

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_017poyHYEyxWEJct9X8Q71qF

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…dience, links

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
preview — 370f9cc8 Deployed Nov 20, 2026 by alukach via Deploy & Test / Deploy #500
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant