Connector delegation

The Connector lets one Ave app act on behalf of a user at another Ave-registered resource. A user approves the connection once; your app can then mint short-lived delegated JWTs whenever it needs to act on their behalf. A common use case: your app needs to access a partner service on a user’s behalf. The user consents via the Connector flow and your app exchanges tokens to get a scoped, time-limited JWT that the partner service accepts.

How it works

Start the connector consent flow

Redirect the user to https://aveid.net/connect with the target resource key, the scopes you want, and the communication mode.

const url = new URL("https://aveid.net/connect");
url.searchParams.set("client_id", "YOUR_CLIENT_ID");
url.searchParams.set("redirect_uri", "https://yourapp.com/callback");
url.searchParams.set("resource", "target-resource-key");
url.searchParams.set("scope", "resource.read");
url.searchParams.set("mode", "user_present");
url.searchParams.set("state", state);

window.location.href = url.toString();

resource is the resource key of the target Ave-registered resource (not a URL). scope must be one of the scopes defined by the target resource. mode is either user_present or background.

User approves the grant

The user sees the target resource’s information and what scopes your app is requesting. They choose which identity to use and approve. If they approve, Ave redirects back to your redirect_uri with a standard ?code=...&state=....

Exchange the authorization code

Exchange the code exactly like a regular auth code flow to get a source app access token:

import { exchangeCodeServer } from "@ave-id/sdk/server";

const sourceTokens = await exchangeCodeServer(
  {
    clientId: "YOUR_CLIENT_ID",
    clientSecret: process.env.AVE_CLIENT_SECRET!,
    redirectUri: "https://yourapp.com/callback",
  },
  { code }
);

// sourceTokens.access_token_jwt is what you use for the next step

Exchange for a delegated token

Use the token-exchange grant to mint a short-lived delegated JWT scoped to the target resource:

POST https://api.aveid.net/api/oauth/token
Content-Type: application/json

{
  "grantType": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subjectToken": "ACCESS_TOKEN_JWT_FROM_PREVIOUS_STEP",
  "requestedResource": "target-resource-key",
  "requestedScope": "resource.read",
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET"
}

Use access_token_jwt as the subjectToken, not the opaque access_token. The server validates the JWT to resolve the user and client identity.

Use the delegated token at the target resource

The response contains a access_token that is a short-lived delegated JWT. Send it to the target resource API as a bearer token:

const response = await fetch("https://partner-service.example.com/api/data", {
  headers: {
    Authorization: `Bearer ${delegatedTokens.access_token}`,
  },
});

The delegated JWT expires in 10 minutes. Re-exchange when it expires (as long as the grant is still active).

Token exchange request

string

required

Must be exactly urn:ietf:params:oauth:grant-type:token-exchange.

string

required

The access_token_jwt from the source app’s token response. The server validates this JWT to identify the user and confirm the client ID.

string

required

The target resource key (as registered in the developer portal).

string

required

The scope(s) to include in the delegated token. Must be a subset of what was originally granted.

string

required

Your source app’s client ID.

string

required

Your source app’s client secret. This is a server-only call.

Token exchange response

string

A signed delegated JWT. Send this as the bearer token to the target resource.

string

Always Bearer.

number

Token lifetime in seconds. Delegated tokens have a fixed 10-minute TTL.

string

The actual scopes included in the delegated token.

string

The audience of the target resource. The target resource should validate this.

string

The target resource key.

string

Either user_present or background, as set when the grant was created.

Delegated JWT payload

The access_token from the exchange is a JWT with the following claims:

{
  "iss": "https://aveid.net",
  "sub": "identity-uuid",
  "aud": "target-resource-audience",
  "exp": 1712345678,
  "iat": 1712342078,
  "sid": "user-uuid",
  "cid": "source_app_client_id",
  "scope": "resource.read",
  "grant_id": "grant-uuid",
  "target_resource": "target-resource-key",
  "com_mode": "user_present"
}

The target resource should validate:

Signature against Ave’s JWKS
aud matches its registered audience
iss is https://aveid.net
exp > now
scope contains the required scope for the action
cid is a known/trusted source app (optional but recommended)

Server-side enforcement

Ave enforces these rules on every token exchange:

subjectToken must decode to a valid JWT belonging to the same clientId
The target resource must exist and be active
The delegation grant must exist and not be revoked
requestedScope must be a subset of the granted scope
requestedScope must be a known scope of the target resource

Grant management

Users can revoke grants. Your app should handle access_denied errors gracefully:

try {
  const delegatedTokens = await exchangeDelegatedTokenServer(config, {
    subjectToken: sourceAccessTokenJwt,
    requestedResource: "target-resource-key",
    requestedScope: "resource.read",
  });
} catch (err) {
  if (err.error === "access_denied") {
    // User revoked the grant — redirect them to re-connect
  }
}

You can also list and revoke grants via:

GET /api/oauth/delegations — list active grants (requires Ave session auth)
DELETE /api/oauth/delegations/:delegationId — revoke a grant

Error reference

Error	Cause
`invalid_grant`	`subjectToken` is invalid, expired, or for the wrong client
`invalid_target`	Target resource key does not exist or is inactive
`access_denied`	No active grant exists for this user/resource/source combination
`invalid_scope`	Requested scope exceeds granted scope or is not defined by the resource

Start

OAuth

Frameworks

Capabilities

Connector delegation

How it works

Token exchange request

Token exchange response

Delegated JWT payload

Server-side enforcement

Grant management

Error reference

​How it works

​Token exchange request

​Token exchange response

​Delegated JWT payload

​Server-side enforcement

​Grant management

​Error reference

How it works

Token exchange request

Token exchange response

Delegated JWT payload

Server-side enforcement

Grant management

Error reference