OAuth for External APIs

The library includes full OAuth 2.0 support for external APIs.

Basic OAuth Setup

typescript

import { OAuthManager, FileStorage } from 'oneringai';

const oauth = new OAuthManager({
  flow: 'authorization_code',
  clientId: process.env.GITHUB_CLIENT_ID!,
  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
  authorizationUrl: 'https://github.com/login/oauth/authorize',
  tokenUrl: 'https://github.com/login/oauth/access_token',
  redirectUri: 'http://localhost:3000/callback',
  scope: 'repo user',

  // Token storage
  storage: new FileStorage({
    directory: './tokens',
    encryptionKey: process.env.OAUTH_ENCRYPTION_KEY!,
  }),
});

// Start OAuth flow
const authUrl = await oauth.startAuthFlow('user-123');
console.log('Visit:', authUrl);

// After user authorizes and is redirected back with ?code=...&state=...
await oauth.handleCallback(callbackUrl, 'user-123');  // Result can be ignored for ordinary OAuth API access

// Use token
const accessToken = await oauth.getToken('user-123');  // returns the access token string

OpenID Connect callback result

OAuthManager.handleCallback() and Connector.handleCallback() return an OAuthCallbackResult ({ idToken?: string }), exported from oneringai. For providers that return id_token, the result contains that raw token; otherwise it is {}. Existing callers can continue to ignore the result. Wrappers explicitly typed as Promise<void> must either await and discard the result or update their return type.

An ID token is not verified by this API. Before using it to authenticate a user, the host must verify its signature, issuer, exact client audience, expiry and the attempt's nonce. The library does not persist it in StoredToken, make it available through getToken(), or return it again during access-token refresh. Do not log the ID token or expose it to an untrusted client. Access and refresh token storage and user/account scoping are unchanged.

Authenticated Fetch

typescript

import { createAuthenticatedFetch } from 'oneringai';

// Create connector for external API using a pre-obtained access token
Connector.create({
  name: 'github',
  serviceType: Services.Github,
  baseURL: 'https://api.github.com',
  auth: {
    type: 'api_key',
    apiKey: userToken.access_token,
    headerName: 'Authorization',
    headerPrefix: 'Bearer',
  },
});

// Create authenticated fetch
const githubFetch = createAuthenticatedFetch('github');

// Make API calls using the configured static token; API-key auth cannot refresh it
const response = await githubFetch('https://api.github.com/user/repos');
const repos = await response.json();

OAuth as a Connector

For automatic refresh, configure auth.type: 'oauth' with token storage and the provider flow. The static-token example below is useful only when the host owns refresh and replaces the credential.

typescript

// Create connector with a pre-obtained access token
Connector.create({
  name: 'microsoft-graph',
  serviceType: Services.Microsoft,
  baseURL: 'https://graph.microsoft.com/v1.0',
  auth: {
    type: 'api_key',
    apiKey: token.access_token,
    headerName: 'Authorization',
    headerPrefix: 'Bearer',
  },
});

// Use in tools
const listEmailsTool: ToolFunction = {
  definition: {
    type: 'function',
    function: {
      name: 'list_emails',
      description: 'List user emails',
      parameters: { type: 'object', properties: {}, required: [] },
    },
  },
  execute: async () => {
    const fetch = createAuthenticatedFetch('microsoft-graph');
    const response = await fetch('/me/messages');
    return await response.json();
  },
};

// Use with agent
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [listEmailsTool],
});

await agent.run('Show me my recent emails');