Authorization
Since Intent providers can read and write data from the LLM-based platform, typically involving user information and message context from the server, it is essential to authorize these Intent providers to ensure they have the proper access permissions.
We recommend LLM-based platforms provide two methods for authorizing Intent providers:
- App Access Token: This token allows the Intent provider to access non-user-specific data, such as the platform's configuration, frequency limit, quota limit, etc.
- User Access Token: This token allows the Intent provider to access user-specific data, such as the user's profile and message context.
Both types of tokens should be capable of generating an access token, a TTL (Time To Live), and a refresh token. The TTL specifies the token's validity period, and the refresh token is used to obtain a new token after the TTL expires. All these tokens should comply with the OAuth 2.0 standard, which requires:
- Client ID
- Client Secret
- Redirect URI
App Access Token
We recommend generating this token using the client credentials grant flow (opens in a new tab), which is intended solely for server-to-server API requests that use an app access token.
User Access Token
There are four types of OAuth 2.0 grant flows that can be used to generate a user access token:
OIDC Implicit Grant Flow
This flow is designed for apps that don’t use a server, such as client-side JavaScript apps or mobile apps. To obtain a user access token using the implicit grant flow (opens in a new tab), navigate a user to https://your-platform.com/oauth2/authorize with appropriate query parameters. This can be done via application control logic or an HTML hyperlink (e.g., <a href="https://your-platform.com/oauth2/authorize?[parameters]">Connect with Your Platform</a>).
The process is similar to logging in with Google or Facebook. The user will be redirected to the platform's login page, and after logging in, they will be redirected back to the redirect URI with the access token and ID token if requested.
OAuth Implicit Code Grant Flow
This flow is also intended for apps that don’t use a server, such as client-side JavaScript apps or mobile apps. To get a user access token using the implicit grant flow (opens in a new tab), but this flow cannot request the ID token, only the access token.
OIDC Authorization Code Grant Flow
This flow is meant for apps that use a server, can securely store a client secret, and can make server-to-server requests to the platform's API. To obtain a user access token using the authorization code grant flow (opens in a new tab), first, get the user to authorize your app’s access to their resources by navigating to https://your-platform.com/oauth2/authorize. After the user logs in, the platform will redirect them to the redirect URI with the authorization code. You can then exchange the authorization code for the access token and ID token if requested.
This process allows you to store the tokens on your server and bind them to the user's session, ensuring the user doesn't need to log in every time they access the platform. This is useful for multiple apps and domains, allowing you to share the user's session between them.
OAuth Authorization Code Grant Flow
This flow is meant for apps that use a server, can securely store a client secret, and can make server-to-server requests to the API. To get a user access token using the authorization code grant flow (opens in a new tab), your app must get the user to authorize your app and then use the authorization code to get a token like the OIDC Authorization Code Grant Flow.
The difference between OIDC Authorization Code Grant Flow and OAuth Authorization Code Grant Flow is that OIDC Authorization Code Grant Flow will return the ID token, and OAuth Authorization Code Grant Flow will not.
Refreshing Token
The lifetime of an access token depends on how you acquired the token. When you get a token, the expires_in field indicates how long, in seconds, the token is valid. When a token expires, it becomes invalid, and any API call made with an invalid token will return a 401 Unauthorized response.
When you get a user access token using the Authorization Code Grant flow, you also receive a refresh token. Refresh tokens are generally used to extend the lifetime of a given authorization. Your app uses the refresh token to get a new access token after receiving a 401 Unauthorized response. However, refresh tokens can also become invalid if the user changes their password or disconnects your app.
Validating Token
The authorization service should provide an https://your-platform.com/oauth2/validate endpoint that you can use to validate your OAuth access token or discover information about the token, such as when it expires, its scopes, and the user who authorized the client to access their resources.
Revoking Token
If the app no longer needs an access token, the LLM-based platform should provide an endpoint to revoke it by sending an HTTP POST request to https://your-platform.com/oauth2/revoke.