App Registry Protocol

Register internal applications, manage cross-app access grants, and verify service-to-service JWTs using the EDS App Registry.

Overview#

The App Registry is EDS's service-to-service authentication system. It allows internal applications to securely communicate with each other using long-lived JWTs (JSON Web Tokens) signed by EDS. Instead of sharing API keys between services, each app registers with EDS and receives tokens scoped to specific target applications.

Tokens are signed with RSA (RS256) and can be verified locally by any app using the public JWKS endpoint — no callback to EDS required at verification time.

How It Works#

1
Register your app
An admin registers your application in the App Registry dashboard. Each app receives a unique app ID and can optionally provide a callback URL and LLM documentation URL.
2
Create an access grant
An admin creates a grant that allows your app (the source) to communicate with a target app. Grants are directional — app A granted access to app B does not imply app B can call app A.
3
Generate a token
Your app requests a JWT from EDS by specifying the target app ID. EDS verifies the grant exists and returns a long-lived RS256-signed JWT with the target app as the audience.
4
Use the token
Send the JWT in the Authorization header when calling the target app. The target app verifies the token locally using the EDS JWKS endpoint — no network call to EDS at request time.

JWT Structure#

Tokens issued by the App Registry contain the following claims:

{
  "iss": "https://eds.jlstradingco.com",   // Issuer — always the EDS host
  "sub": "source-app-uuid",                 // Subject — the app that requested the token
  "aud": "target-app-uuid",                 // Audience — the app the token is intended for
  "app_name": "My Internal Tool",           // Human-readable name of the source app
  "iat": 1713200000,                        // Issued at (Unix timestamp)
  "exp": 1744800000                         // Expires at (Unix timestamp, 1 year default)
}

*iss— The issuer is always your EDS deployment's base URL.
*sub— The source application's unique ID in the App Registry.
*aud— The target application's unique ID. Your app should always verify this matches your own app ID.
*app_name — A human-readable name for the source app, useful for logging and audit trails.
*exp — Tokens expire after 1 year by default. Always check expiry before trusting a token.

Verifying Tokens in Your App#

Use the jose library to verify tokens locally. The JWKS endpoint provides the public keys needed for RS256 signature verification.

import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(
  new URL("/.well-known/jwks.json", "https://eds.jlstradingco.com")
);

const YOUR_APP_ID = "<your-app-id-from-the-registry>";

async function verifyAppToken(token: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: "https://eds.jlstradingco.com",
    audience: YOUR_APP_ID,
  });

  return {
    sourceAppId: payload.sub,
    sourceAppName: payload.app_name,
  };
}

Local verification

The jose library caches the JWKS keys automatically. After the first fetch, token verification happens entirely in-process with no network calls to EDS. This means verification is fast and does not depend on EDS availability.

Best Practices#

*Always check the aud (audience) claim matches your app's registered ID. Accepting tokens intended for other apps is a security vulnerability.
*Log the source app ID (sub) and name (app_name) for audit trails. This helps trace which app made each request.
*Handle token expiry gracefully. If verification fails with an expiry error, the calling app needs to request a fresh token from EDS.
*Cache the JWKS keys. The jose library does this automatically, but if you implement verification manually, cache the keys and refresh them periodically or when verification fails with an unknown key ID.

JWKS Endpoint#

Public JSON Web Key Set for token verification