Skip to main content

Accessing a connection's API via access tokens

Authress provides login aggregation, and it makes federated login easier. It does this by creating optimized user access tokens to be used and verified by service APIs. Authress creates access tokens specifically for your application.

During the login process, the third party provider configured as an Authress OAuth Connection, can save the login credentials in a credentials vault. This vault enables your user in your app's UI or through an app's API to connect to the third party using the credential saved in the vault.

Credentials Vault

Authress is able to connect with any registered OAuth provider. The result of the login with the third party provider is a credential saved in the Authress Credentials Vault.

When an access token is requested from the connection's credentials vault, Authress determines if the current available token will still be valid for a sufficient length of time, and if not will automatically refresh it to generate a new access token. It does this using the OAuth configuration in the connection, and without ever revealing the refresh token at any time.

Refreshing the access token after it expires is part of OAuth, and every OAuth provider configured in Authress supports this. However, some of them need to be explicitly configured using the OAuth Refresh or Offline access configuration.


The critical step is to configure the federated login provider to make sure it also returns a long lived refresh token. This is usually done via the connectionProperties on authentication. For the Google OAuth connection provider, refresh tokens are generated when the access_type property is configured to be offline.

_(Note: This is the configuration for the Google connection, other OAuth connections may use a different and non-standard configuration to enable this functionality. Make sure to review the connection provider's documentation before configuring the connection)._

Additionally, Google may not always return the necessary refresh token, in these cases, be sure to follow closely the Google login OAuth client setup and use the following connectionProperties as strictly documented here:

import { LoginClient } from 'authress-login';

const loginClient = new LoginClient({
authressLoginHostUrl: '',
applicationId: 'Application_ID' });

await loginClient.authenticate({ connectionId: 'google',
// For Google login, offline access is configured via `access_type` property
connectionProperties: {
scope: 'email openid profile additional_google_scope',
access_type: 'offline',
// Refresh token still missing, add this line:
prompt: 'select_account consent'

Client side access

After a user logs in with their selected OAuth identity provider and is redirected through Authress back to your application UI, there is an opportunity to exchange the Authress JWT for the provider credential. If the UI decides to interact with the provider's API directly in the browser, the Authress Login SDK can be used to fetch the provider access token:

import { loginClient } from 'authress-login';

async function makeProviderApiCall() {
const credentials = await loginClient.getConnectionCredentials();
const accessToken = credentials.accessToken;
const result = await request('',
{ 'Authorization': `Bearer ${accessToken}` });
return result;

Service side access

Alternatively, requests may want to be made async from the service side, even when the user isn't logged in. There may be relevant background tasks that need to be performed, or long running actions. (Here are examples of long running transaction architecture in case one of those patterns better matches the use case).

In this circumstance, the context is the service client. Since the credentials are saved in the Authress connection vault, create and grant a service client the Authress role: UserCredentialsViewer to Authress:Connections/*/Users/*/Credentials, and then the service client can access the credentials for the user:

const { AuthressClient } = require('authress-sdk');

async function makeProviderApiCall() {
// Your authress custom domain, found:
const host = '';
// The user's access token generated by Authress, sent to your API
const userAccessTokenFromAuthress = 'ey...';
// The provider's OAuth connection registered in Authress
const connectionId = 'con-AAyzR1';

const authressClient = new AuthressClient({ baseUrl: host })
const response = await authressClient.connections.getConnectionCredentials(connectionId);
const accessToken =;

// Make the API call to the third party's API:
const result = await request('',
{ 'Authorization': `Bearer ${accessToken}` });
return result;

Additional resources

Take a look at the full API documentation to see what else is possible.