Skip to main content
Delegation grants allow users to authorize one app to access another app’s resources on their behalf. These endpoints let users view and manage their active connector delegations.

​
List Delegations

Retrieve all connector delegation grants for the authenticated user.

​
Authentication

Requires a valid session token in the Authorization header: 
Authorization: Bearer <session_token>
This endpoint requires a session token, not an OAuth access token. Session tokens are obtained through the login flow.

​
Response

​
delegations
array
Array of delegation grant objects

​
Example Request

import { listDelegations } from '@ave-id/sdk';

const delegations = await listDelegations(
  { issuer: 'https://aveid.net' },
  sessionToken
);

for (const grant of delegations) {
  console.log(`${grant.sourceAppName} → ${grant.targetResourceName}`);
  console.log(`Scopes: ${grant.scope}`);
  console.log(`Mode: ${grant.communicationMode}`);
}

​
Example Response

{
  "delegations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "revokedAt": null,
      "communicationMode": "user_present",
      "scope": "read write",
      "sourceAppClientId": "app_source123",
      "sourceAppName": "Analytics Dashboard",
      "sourceAppIconUrl": "https://cdn.example.com/analytics-icon.png",
      "sourceAppWebsiteUrl": "https://analytics.example.com",
      "targetResourceKey": "crm-api",
      "targetResourceName": "CRM API",
      "targetAudience": "https://api.crm.example.com"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "createdAt": "2024-01-14T15:20:00Z",
      "updatedAt": "2024-01-16T09:15:00Z",
      "revokedAt": null,
      "communicationMode": "background",
      "scope": "read notifications",
      "sourceAppClientId": "app_source456",
      "sourceAppName": "Notification Service",
      "sourceAppIconUrl": "https://cdn.example.com/notify-icon.png",
      "sourceAppWebsiteUrl": "https://notify.example.com",
      "targetResourceKey": "messaging-api",
      "targetResourceName": "Messaging API",
      "targetAudience": "https://api.messaging.example.com"
    }
  ]
}

​
Revoke Delegation

Revoke a connector delegation grant, preventing the source app from accessing the target resource.

​
Authentication

Requires a valid session token in the Authorization header.

​
Path Parameters

​
delegationId
string
required
The ID of the delegation grant to revoke

​
Response

​
success
boolean
Returns true if revocation was successful

​
Example Request

import { revokeDelegation } from '@ave-id/sdk';

await revokeDelegation(
  { issuer: 'https://aveid.net' },
  sessionToken,
  delegationId
);

console.log('Delegation revoked successfully');

​
Example Response

{
  "success": true
}

​
Error Response

Delegation Not Found
{
  "error": "Delegation not found"
}

​
Communication Modes

Delegation grants support two communication modes:

user_present

The source app can only access the target resource when the user is actively present and interacting with the source app. This is more restrictive and suitable for interactive operations.

background

The source app can access the target resource in the background, even when the user is not actively using the app. This enables automation and scheduled tasks.
The communication mode is set during the connector authorization flow and included in delegated access tokens.

​
Audit Logs

All delegation operations are logged in the audit log:
  • grant_created - When a new delegation grant is created
  • grant_revoked - When a delegation grant is revoked
  • token_exchanged - When a delegated token is issued
Audit logs include:
  • Grant ID
  • User ID
  • Source app ID
  • Target resource ID
  • Event details (requested scopes, communication mode, etc.)

​
Use Cases

​
App Integration Dashboard

Build a settings page where users can see which apps have connector access: 
import { listDelegations, revokeDelegation } from '@ave-id/sdk';

function IntegrationsSettings({ sessionToken }) {
  const [delegations, setDelegations] = useState([]);

  useEffect(() => {
    async function load() {
      const grants = await listDelegations({}, sessionToken);
      setDelegations(grants);
    }
    load();
  }, [sessionToken]);

  async function handleRevoke(id) {
    await revokeDelegation({}, sessionToken, id);
    setDelegations(prev => prev.filter(d => d.id !== id));
  }

  return (
    <div>
      <h2>Connected Apps</h2>
      {delegations.map(grant => (
        <div key={grant.id}>
          <img src={grant.sourceAppIconUrl} />
          <div>
            <strong>{grant.sourceAppName}</strong>
            <p>Can access {grant.targetResourceName}</p>
            <p>Scopes: {grant.scope}</p>
            <p>Mode: {grant.communicationMode}</p>
          </div>
          <button onClick={() => handleRevoke(grant.id)}>
            Revoke Access
          </button>
        </div>
      ))}
    </div>
  );
}

​
Automatic Cleanup

Revoke all delegations for a specific app: 
import { listDelegations, revokeDelegation } from '@ave-id/sdk';

async function revokeAllForApp(sessionToken: string, appClientId: string) {
  const delegations = await listDelegations({}, sessionToken);
  
  const toRevoke = delegations.filter(
    d => d.sourceAppClientId === appClientId && !d.revokedAt
  );
  
  await Promise.all(
    toRevoke.map(d => revokeDelegation({}, sessionToken, d.id))
  );
  
  console.log(`Revoked ${toRevoke.length} delegation grants`);
}
Security: Revoked delegations cannot be restored. Users must go through the connector authorization flow again to re-establish access.

Build docs developers (and LLMs) love

Get started for freeTalk to us