Rate this page:
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 2import api from '@forge/api'; const response = await api.asUser() .withProvider('google', 'google-apis') .fetch('/userinfo/v2/me');
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 2fetch(url[, options])
Name | Type | Required | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
url | string | Yes |
Relative path from the remote specified in withProvider. If the
| ||||||||||||
options | object | See the node-fetch library’s Options documentation for the accepted values. |
Determines if the user is authenticated.
1 2api.asUser().withProvider(provider).hasCredentials() => Promise<boolean>
1 2const [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'); ... })
Triggers the OAuth 2.0 consent flow. The app is replaced with a button for the user to select to start the flow.
1 2api.asUser().withProvider(provider).requestCredentials()
1 2if (!await api.asUser().withProvider(provider).hasCredentials()) { await api.asUser().withProvider(provider).requestCredentials() }
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 2AuthProfile({id, displayName, avatarUrl})
Property | Type | Required | Description |
---|---|---|---|
id | string | Yes | Used to de-duplicate accounts and add new accounts. Must be a unique string per account. |
displayName | string | Yes |
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. |
avatarUrl | string | URL providing the avatar picture. |
1 2interface 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 } }
1 2withProvider(provider[, remoteName])
Rate this page: