Async events API
Fetch API
Storage API

Rate this page:

External authentication

The withProvider method enables your Forge app to communicate with an API that requires OAuth 2.0 tokens. Access is via the asUser method, in the @forge/api package.

1
2
3
4
5
import api from '@forge/api';

const response = await api.asUser()
      .withProvider('google', 'google-apis')
      .fetch('/userinfo/v2/me');

fetch

Before using fetch for authenticated requests, ensure the user is valid with hasCredentials or requestCredentials. If the user is not authenticated, an exception is raised.

Once a user is authenticated, the fetch method automatically includes their authentication token for each request.

Apps using external authentication must define the external domains in the remotes section of the manifest file. See Remotes.

1
fetch(url[, options])
NameTypeRequiredDescription
urlstringYes

Relative path from the remote specified in withProvider.

If the url parameter starts with a /, the remote baseUrl path is ignored.

Remote baseUrlFetch urlResult
https://example.atlassian.com/api/v1//api/v1/endpointhttps://example.atlassian.com/api/v1/endpoint
https://example.atlassian.com/api/v1/endpointhttps://example.atlassian.com/api/v1/endpoint
https://example.atlassian.com/api/v1//endpointhttps://example.atlassian.com/endpoint
optionsobject

See the node-fetch library’s Options documentation for the accepted values.

hasCredentials

Determines if the user is authenticated.

Method signature

1
api.asUser().withProvider(provider).hasCredentials() => Promise<boolean>

Example usage

1
2
3
4
5
6
7
8
const [data] = useState(async () => {
  const google = api.asUser().withProvider('google', 'google-apis');
  if (!await google.hasCredentials()) {
    await google.requestCredentials();
  }
  const response = await google.fetch('/userinfo/v2/me');
  ...
})

requestCredentials

Triggers the OAuth 2.0 consent flow. The app is replaced with a button for the user to select to start the flow.

1
api.asUser().withProvider(provider).requestCredentials()

Example usage

1
2
3
if (!await api.asUser().withProvider(provider).hasCredentials()) {
  await api.asUser().withProvider(provider).requestCredentials()
}

AuthProfile

The return value of a dynamic profile retriever should be an AuthProfile object. See the dynamic profile retriever guide for more information.

The file containing a dynamic profile retriever cannot import @forge/ui, because when executed, the dynamic profile retriever is run in a different context outside of the UI.

1
AuthProfile({id, displayName, avatarUrl})
PropertyTypeRequiredDescription
idstringYes

Used to de-duplicate accounts and add new accounts. Must be a unique string per account.

displayNamestringYes

Account name displayed to the user for the purpose of distinguishing between multiple accounts.

Should be one of email, username, or some other unique identifier that the user would recognize.

This should NOT be a name value, as that may be the same across multiple accounts.

avatarUrlstring

URL providing the avatar picture.

Example usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
interface ProfileRetrieverParameters {
  status: number;
  body: {
    [key: string]: any;
  };
}

export const retriever = (response: ProfileRetrieverParameters) => {
  const { status, body: externalProfile } = response;

  if (status === 200){
    return new AuthProfile({
      id: externalProfile.user.id,
      displayName: externalProfile.user.name,
    });
  } else {
    // handle error
  }
}

withProvider

1
withProvider(provider[, remoteName])
NameTypeRequiredDescription
providerstringYesThe provider key from the manifest file.
remoteNamestring

The remote to use when using fetch. The remoteName must be in the providers.auth.<key>.remotes list in the manifest file.

remoteName may be omitted if only one remote is defined for the provider.

Rate this page: