Class OAuthClient

OAuth 2.0 client for Contio Partner API authentication.

Supports authorization code flow, client credentials, token refresh, and token introspection. Tokens are opaque (not JWTs) for security.

Example

const oauth = new OAuthClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  redirectUri: 'https://your-app.com/callback',
  scope: ['openid', 'profile', 'meetings:read', 'meetings:write']
});

// Generate authorization URL
const authUrl = oauth.getAuthorizationUrl(crypto.randomUUID());

// After callback, exchange code for tokens
const tokens = await oauth.exchangeCodeForToken(code);

Index

Constructors

constructor

Methods

checkConsent exchangeCodeForToken getAccessToken getAuthorizationUrl getAvailableScopes getClientCredentialsToken getPartnerInfo getUserInfo initiatePartnerAuth introspectToken isTokenExpired refreshAccessToken revokeToken setTokens verifyPartnerAuth

Constructors

constructor

new OAuthClient(config: OAuthConfig): OAuthClient
Create a new OAuthClient instance.
Parameters
- config: OAuthConfig
  OAuth configuration
  - OptionalauthorizationUrl?: string
  - clientId: string
  - clientSecret: string
  - redirectUri: string
  - Optionalscope?: string[]
  - OptionaltokenUrl?: string
Returns OAuthClient
- Defined in src/auth/oauth.ts:56

Methods

checkConsent

checkConsent(
email: string,
): Promise<
{ hasConsent: boolean; redirectUrl?: string; requiresConsent: boolean },
>
Check if a user has already granted consent for the requested scopes.

Use this to determine if you can skip the consent screen for returning users.
Parameters
- email: string
  User's email address
Returns Promise<{ hasConsent: boolean; redirectUrl?: string; requiresConsent: boolean }>
Consent status and optional redirect URL

Throws
If the check fails
- Defined in src/auth/oauth.ts:451

exchangeCodeForToken

exchangeCodeForToken(code: string): Promise<AuthTokens>
Exchange an authorization code for access and refresh tokens.

Call this after the user is redirected back to your app with an authorization code. The tokens are automatically stored in the client for subsequent API calls.
Parameters
- code: string
  The authorization code from the callback URL query parameter
Returns Promise<AuthTokens>
The token set including access token, refresh token, and expiration
Throws
If the code is invalid, expired, or already used
Example
```
// In your callback handler
const code = req.query.code as string;
const tokens = await oauth.exchangeCodeForToken(code);

// Store tokens securely for later use
await storeTokens(userId, tokens);
```
- Defined in src/auth/oauth.ts:138

getAccessToken

getAccessToken(): string | undefined
Get the current access token stored in the client.

Returns string | undefined
The access token, or undefined if not authenticated
- Defined in src/auth/oauth.ts:304

getAuthorizationUrl

getAuthorizationUrl(state?: string, options?: AuthorizationUrlOptions): string
Generate the authorization URL for OAuth flow
Parameters
- Optionalstate: string
  Optional CSRF protection state parameter
- Optionaloptions: AuthorizationUrlOptions
  Optional additional parameters (e.g., loginHint to pre-fill email)
Returns string
The authorization URL to redirect users to
Example
```
// Basic usage
const url = oauth.getAuthorizationUrl('random-state');

// With login_hint to pre-fill and lock email
const url = oauth.getAuthorizationUrl('random-state', {
  loginHint: 'user@example.com'
});
```
- Defined in src/auth/oauth.ts:105

getAvailableScopes

getAvailableScopes(): Promise<string[]>
Get the list of available OAuth scopes.

Returns Promise<string[]>
Array of available scope strings

Throws
If the request fails
- Defined in src/auth/oauth.ts:513

getClientCredentialsToken

getClientCredentialsToken(scope?: string[]): Promise<AuthTokens>
Get an access token using client credentials grant.

Use this for server-to-server authentication where no user context is needed. This is typically used for admin operations or background jobs.
Parameters
- Optionalscope: string[]
  Optional scopes to request; uses configured scopes if not provided
Returns Promise<AuthTokens>
Token set (no refresh token for client credentials)
Throws
If authentication fails
Example
```
const tokens = await oauth.getClientCredentialsToken(['admin:read']);
```
- Defined in src/auth/oauth.ts:233

getPartnerInfo

getPartnerInfo(): Promise<
    {
        description?: string;
        logoUrl?: string;
        name: string;
        websiteUrl?: string;
    },
>
Get public partner app information.

This endpoint does not require authentication and is safe to call from frontend code. Use it to display partner branding on login screens.

Returns Promise<
    {
        description?: string;
        logoUrl?: string;
        name: string;
        websiteUrl?: string;
    },
>
Partner app public information (name, logo, etc.)

Throws
If the partner app is not found
- Defined in src/auth/oauth.ts:490

getUserInfo

getUserInfo(
accessToken?: string,
): Promise<{ email?: string; name?: string; picture?: string; sub: string }>
Get user information using an access token.

Returns OIDC standard claims about the authenticated user. Requires the 'openid' and 'profile' scopes.
Parameters
- OptionalaccessToken: string
  Optional access token; uses stored token if not provided
Returns Promise<{ email?: string; name?: string; picture?: string; sub: string }>
User information including subject ID, email, name, and picture
Throws
If no access token is available or the request fails
Example
```
const userInfo = await oauth.getUserInfo();
console.log(`Hello, ${userInfo.name}!`);
console.log(`Email: ${userInfo.email}`);
```
- Defined in src/auth/oauth.ts:600

initiatePartnerAuth

initiatePartnerAuth(
    email: string,
    name?: string,
    options?: InitiatePartnerAuthOptions,
): Promise<
    {
        challengeName: string;
        challengeParams?: Record<string, string>;
        session: string;
        userProvisioned?: boolean;
    },
>
Initiate partner passwordless authentication.

Starts the passwordless login flow by sending a verification code to the user's email. Use this for embedded authentication flows within your app.
Parameters
- email: string
  User's email address
- Optionalname: string
  Optional user's name (used for new user provisioning)
- Optionaloptions: InitiatePartnerAuthOptions
  Optional shared workspace configuration
  
  Options for initiating partner authentication with shared workspace support.
  - Optionalis_admin?: boolean
    When true, assigns WORKSPACE_ADMIN role instead of WORKSPACE_MEMBER when joining a shared workspace. Ignored when workspace_id is not provided.
    
    Default
    false
  - Optionalworkspace_id?: string
    Target workspace for the new user. If omitted, a personal workspace is created for the user (preserving current default behavior).
Returns Promise<
    {
        challengeName: string;
        challengeParams?: Record<string, string>;
        session: string;
        userProvisioned?: boolean;
    },
>
Session info for completing authentication
Throws
If initiation fails

Throws
workspace_not_found (400) if workspace_id does not exist

Throws
workspace_not_authorized (403) if the workspace is not owned by a user from the same partner

Throws
workspace_conflict (409) if the user is already in a different workspace
Example
```
// Provision user into a shared workspace as admin
const result = await oauth.initiatePartnerAuth(
  'newuser@example.com',
  'New User',
  { workspace_id: 'workspace-uuid', is_admin: true }
);
```
- Defined in src/auth/oauth.ts:369

introspectToken

introspectToken(
    token: string,
): Promise<
    {
        active: boolean;
        clientId?: string;
        exp?: number;
        iat?: number;
        scope?: string;
        username?: string;
    },
>
Introspect an access token to check its validity and metadata.

Since Contio uses opaque tokens (not JWTs), you cannot decode them locally. Use this method to check if a token is still valid and get its metadata.
Parameters
- token: string
  The access token to introspect
Returns Promise<
    {
        active: boolean;
        clientId?: string;
        exp?: number;
        iat?: number;
        scope?: string;
        username?: string;
    },
>
Token metadata including active status, scopes, and expiration
Throws
If introspection fails
Example
```
const info = await oauth.introspectToken(accessToken);
if (!info.active) {
  // Token is expired or revoked, refresh it
  await oauth.refreshAccessToken();
}
console.log('Scopes:', info.scope);
console.log('Expires:', new Date(info.exp * 1000));
```
- Defined in src/auth/oauth.ts:554

isTokenExpired

isTokenExpired(): boolean
Check if the current access token is expired.

Returns boolean
true if the token is expired or expiration is unknown, false otherwise
- Defined in src/auth/oauth.ts:335

refreshAccessToken

refreshAccessToken(refreshToken?: string): Promise<AuthTokens>
Refresh the access token using a refresh token.

Access tokens expire after 24 hours. Use this method to get a new access token without requiring the user to re-authorize. Refresh tokens are valid for 30 days.
Parameters
- OptionalrefreshToken: string
  Optional refresh token; uses stored token if not provided
Returns Promise<AuthTokens>
New token set with fresh access token
Throws
If no refresh token is available or the token is invalid/expired
Example
```
// Proactively refresh before expiration
if (oauth.isTokenExpired()) {
  const newTokens = await oauth.refreshAccessToken();
  await storeTokens(userId, newTokens);
}
```
- Defined in src/auth/oauth.ts:185

revokeToken

revokeToken(
token: string,
tokenType?: "refresh_token" | "access_token",
): Promise<void>
Revoke an access or refresh token.

Use this when a user disconnects your app or you need to invalidate tokens. Revoked tokens cannot be used for API calls.
Parameters
- token: string
  The token to revoke
- tokenType: "refresh_token" | "access_token" = 'access_token'
  Type of token: 'access_token' or 'refresh_token' (default: 'access_token')
Returns Promise<void>
Throws
If revocation fails
Example
```
// Revoke when user disconnects
await oauth.revokeToken(tokens.accessToken, 'access_token');
await oauth.revokeToken(tokens.refreshToken, 'refresh_token');
```
- Defined in src/auth/oauth.ts:276

setTokens

setTokens(tokens: AuthTokens): void
Set tokens directly from storage.

Use this to restore tokens from your secure storage when initializing the client for a returning user.
Parameters
- tokens: AuthTokens
  Previously stored token set
Returns void
Example
```
// Restore tokens from database
const storedTokens = await getStoredTokens(userId);
oauth.setTokens(storedTokens);

// Now the client can make authenticated requests
const meetings = await user.getMeetings();
```
- Defined in src/auth/oauth.ts:326

verifyPartnerAuth

verifyPartnerAuth(
    email: string,
    code: string,
    session: string,
): Promise<{ redirectUrl?: string }>
Verify partner passwordless authentication.

Completes the passwordless login flow by verifying the code sent to the user's email.
Parameters
- email: string
  User's email address
- code: string
  Verification code from email
- session: string
  Session ID from initiatePartnerAuth
Returns Promise<{ redirectUrl?: string }>
Redirect URL to complete OAuth flow

Throws
If verification fails or code is invalid
- Defined in src/auth/oauth.ts:413

Class OAuthClient

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

OptionalauthorizationUrl?: string

clientId: string

clientSecret: string

redirectUri: string

Optionalscope?: string[]

OptionaltokenUrl?: string

Returns OAuthClient

Methods

checkConsent

Parameters

Returns Promise<{ hasConsent: boolean; redirectUrl?: string; requiresConsent: boolean }>

Throws

exchangeCodeForToken

Parameters

Returns Promise<AuthTokens>

Throws

Example

getAccessToken

Returns string | undefined

getAuthorizationUrl

Parameters

Returns string

Example

getAvailableScopes

Returns Promise<string[]>

Throws

getClientCredentialsToken

Parameters

Returns Promise<AuthTokens>

Throws

Example

getPartnerInfo

Returns Promise< { description?: string; logoUrl?: string; name: string; websiteUrl?: string; },>

Throws

getUserInfo

Parameters

Returns Promise<{ email?: string; name?: string; picture?: string; sub: string }>

Throws

Example

initiatePartnerAuth

Parameters

Optionalis_admin?: boolean

Default

Optionalworkspace_id?: string

Returns Promise< { challengeName: string; challengeParams?: Record<string, string>; session: string; userProvisioned?: boolean; },>

Throws

Throws

Throws

Throws

Example

introspectToken

Parameters

Returns Promise< { active: boolean; clientId?: string; exp?: number; iat?: number; scope?: string; username?: string; },>

Throws

Example

isTokenExpired

Returns boolean

refreshAccessToken

Parameters

Returns Promise<AuthTokens>

Throws

Example

revokeToken

Parameters

Returns Promise<void>

Throws

Example

setTokens

Parameters

Returns void

Example

verifyPartnerAuth

`Optional`authorizationUrl?: string

`Optional`scope?: string[]

`Optional`tokenUrl?: string

Returns Promise<
{
description?: string;
logoUrl?: string;
name: string;
websiteUrl?: string;
},
>

`Optional`is_admin?: boolean

`Optional`workspace_id?: string

Returns Promise<
{
challengeName: string;
challengeParams?: Record<string, string>;
session: string;
userProvisioned?: boolean;
},
>

Returns Promise<
{
active: boolean;
clientId?: string;
exp?: number;
iat?: number;
scope?: string;
username?: string;
},
>