Descope token-exchange: merge checklist for PR

[hammadtq]

Summary

Add first-class Descope support (JWT exchange) to Attach Gateway.

Context

@toharm’s fork (feature/descope) successfully exchanges an Auth0 JWT for a
Descope app token and passes all manual tests. Let’s upstream it so others can
pip install attach-dev and use Descope out-of-the-box.

Merge checklist

• Keep existing public verify_jwt() API; call the exchange helper inside
• Add pytest that mocks POST /oauth2/v1/apps/token (so CI is green)
• Update README → Other IdPs (Descope) with env-var snippet
• Add CHANGELOG entry under Added

Credits

If you open the PR, we’ll merge with Co-authored-by so you appear in Git logs
and GitHub contributors.

Next steps

@toharm let me know if you have bandwidth. Happy to pair or review.
If not, I can port your branch into contrib/descope and still credit you.

Thanks again for jumping in!
— Hammad

[toharm]

Hi Hammad,

Thanks for reaching out, and I appreciate you putting this in an issue. I do have bandwidth and I am happy to continue working on this.

At the moment, the functionality of exchanging an Auth0 JWT for a Descope JWT works. That said, the broader goal is to eventually remove Auth0 from the flow entirely, solely relying on Descope JWTs. This way, attach-gateway will be able to use Descope's Management Flow for A2A authentication, enabling agents to securely exchange JWTs with configurable audience, scope, and claim sources rather than always sharing the same configurations between agents.

Elaborating further, Descope's Management Flow will allow the backend processes to vary the audience, scope, and claims on a JWT based on the respective requirements of that process, enforcing least privilege for authorized processes.

Some of the capabilities and jwt-bearer endpoint are currently gated behind feature flags, but I'll keep you posted as I continue to make progress. For now, I'll start working on this current checklist.

Looking forward to collaborate further!

Cheers, Tohar

[hammadtq]

Thanks for the context.
Direct Descope verification (no Auth0 hop) would be great to have alongside the current flows.

Let’s do this:

1. Backend selector – we’ll add AUTH_BACKEND=descope so users can choose Descope-only.
2. Env vars – DESCOPE_PROJECT_ID, DESCOPE_JWKS_URL, etc. (I’ll push an updated .env.example).
3. Keep exchange helper – Auth0→Descope path stays available for mixed stacks.
4. Least-privilege demo – once your Management Flow feature flags open up, we can extend scopes/audiences.

I’ll handle the selector plumbing; feel free to keep iterating on the direct verifier + pytest + README bullet.

Sound good? Appreciate the collaboration!

[toharm]

Yes, sounds good! I'll keep you updated on my progress.

[toharm]

Completed merge checklist items:

• Existing verify_jwt() functionality with exchange call inside
• Pytest that mocks POST /oauth2/v1/apps/token and also tests verify_jwt()
• README update

Also looking into opening our Management Flow feature flags.

[hammadtq]

Thanks Tohar!

Re: Management Flow flags – that would be perfect. Once they’re public we can add a follow-up doc section (“Descope Managed A2A”).

Let me know if you need anything on CI or mock tokens.
Really appreciate the contribution.