diff --git a/docs/assets/integrate/oauth2/oauth2-creds.png b/docs/assets/integrate/oauth2/oauth2-creds.png new file mode 100644 index 0000000000..55b2a7089f Binary files /dev/null and b/docs/assets/integrate/oauth2/oauth2-creds.png differ diff --git a/docs/assets/integrate/oauth2/settings-links.png b/docs/assets/integrate/oauth2/settings-links.png new file mode 100644 index 0000000000..cc1c3a066d Binary files /dev/null and b/docs/assets/integrate/oauth2/settings-links.png differ diff --git a/docs/assets/integrate/oauth2/settings-new.png b/docs/assets/integrate/oauth2/settings-new.png new file mode 100644 index 0000000000..2f309de1f0 Binary files /dev/null and b/docs/assets/integrate/oauth2/settings-new.png differ diff --git a/docs/assets/integrate/oauth2/settings-scopes.png b/docs/assets/integrate/oauth2/settings-scopes.png new file mode 100644 index 0000000000..2649c1a56e Binary files /dev/null and b/docs/assets/integrate/oauth2/settings-scopes.png differ diff --git a/docs/assets/integrate/oauth2/settings-till-redirect.png b/docs/assets/integrate/oauth2/settings-till-redirect.png new file mode 100644 index 0000000000..3fe1f4785c Binary files /dev/null and b/docs/assets/integrate/oauth2/settings-till-redirect.png differ diff --git a/docs/integrate/oauth2/connect.mdx b/docs/integrate/oauth2/connect.mdx index 20327834a3..796eb680ce 100644 --- a/docs/integrate/oauth2/connect.mdx +++ b/docs/integrate/oauth2/connect.mdx @@ -3,69 +3,95 @@ title: "OAuth 2.0 Connect" sidebarTitle: "Connect users" --- -## Authorize - -To start the authorization flow you need to redirect the user to the authorization URL. It looks like this: - -``` -https://polar.sh/oauth2/authorize? - response_type=code - &client_id=CLIENT_ID - &redirect_uri=https%3A%2F%2Fexample.com%2Fcallback - &scope=openid%20email -``` - -The parameters are the one described in the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). The most important ones are: - - - Indicates that you want to use the authorization code flow. Most common and - the only one supported by Polar. - - - - The Client ID you got when creating the OAuth 2.0 client. - - - - The URL where the user will be redirected after granting access to their data. Make sure you declared it when creating the OAuth2 client. - - - - A space-separated list of scopes you want to ask for. Make sure they are part of the scopes you declared when creating the OAuth2 client. - - -If you redirect the user to this URL, they'll see a page asking them to grant access to their data, corresponding to the scopes you asked for. - - - -If they allow it, they'll be redirected to your `redirect_uri` with a `code` parameter in the query string. This code is a one-time code that you can exchange for an access token. - -#### Exchange code token - -Once you have the authorization code, you can exchange it for an access token. To do so, you'll need to make a `POST` request to the token endpoint. This call needs to be authenticated with the Client ID and Client Secret you got when creating the OAuth2 client. - -Here is an example with cURL: - -```bash -curl -X POST https://api.polar.sh/v1/oauth2/token \ - -H 'Content-Type: application/x-www-form-urlencoded' \ - -d 'grant_type=authorization_code&code=AUTHORIZATION_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=https://example.com/callback' -``` - -You should get the following response: - -```json -{ - "token_type": "Bearer", - "access_token": "polar_at_XXX", - "expires_in": 864000, - "refresh_token": "polar_rt_XXX", - "scope": "openid email", - "id_token": "ID_TOKEN" -} -``` - -The `access_token` will allow you to make authenticated API requests on behalf of the user. The `refresh_token` is a long-lived token that you can use to get new access tokens when the current one expires. The `id_token` is a signed JWT token containing information about the user, as per the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). + + + To start the authorization flow you need to redirect the user to the authorization URL. It looks like this: + + ``` + https://polar.sh/oauth2/authorize? + response_type=code + &client_id=CLIENT_ID + &redirect_uri=https%3A%2F%2Fexample.com%2Fcallback + &scope=openid%20email + ``` + + + The domain to which the authorize request needs to be made is **polar.sh** (and not api.polar.sh). + + + The parameters are the one described in the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). The most important ones are: + + + Indicates that you want to use the authorization code flow. Most common and + the only one supported by Polar. + + + + Supports: `organization`, `user` + + Indicates the level of access you want to include for your OAuth 2.0 token. + + With `user` - the access of the OAuth 2.0 token is to all the organizations of the user. + + With `organization` - the access of the OAuth 2.0 token is limited to the organization selected by the user. + + + + The Client ID you got when creating the OAuth 2.0 client. + + + + The URL where the user will be redirected after granting access to their data. Make sure you declared it when creating the OAuth2 client. + + + + A space-separated list of scopes you want to ask for. Make sure they are part of the scopes you declared when creating the OAuth2 client. + + If you require `id_token` to be part of the response, make sure to include `openid` as part of the scope. + + + + Once redirected, the user will see a page requesting them to grant access to their data according to the scopes you specified. + + + + If they allow it, they'll be redirected to your set `redirect_uri` with the `code` parameter in the query string. This `code` is a one-time use code that you can exchange for an access token. + + + Once you have the authorization code, you can exchange it for an access token. To do so, you'll need to make [a `POST` request to the token endpoint](/docs/api-reference/oauth2/connect/request-token). This call needs to be authenticated with the Client ID and Client Secret you got when [creating the OAuth2 client](/integrate/oauth2/setup). + + Here is an example with cURL: + + ```bash + curl -X POST https://api.polar.sh/v1/oauth2/token \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'grant_type=authorization_code&code=AUTHORIZATION_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=https://example.com/callback' + ``` + + You should get the following response: + + ```json + { + "token_type": "Bearer", + "access_token": "polar_at_XXX", + "expires_in": 864000, + "refresh_token": "polar_rt_XXX", + "scope": "openid email", + "id_token": "ID_TOKEN" + } + ``` + + The `access_token` will allow you to make authenticated API requests on behalf of the user. The `refresh_token` is a long-lived token that you can use to get new access tokens when the current one expires. The `id_token` is a signed JWT token containing information about the user, as per the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). + + + Once you have an access token, you can make authenticated requests to the API. Here is a simple example with cURL: + + ```bash + curl -X GET https://api.polar.sh/v1/oauth2/userinfo \ + -H 'Authorization: Bearer polar_at_XXX' + ``` + + #### User vs Organization Access Tokens @@ -73,6 +99,10 @@ We support the concept of access tokens at **organization level**. Contrary to t To ask for an organization access token, you need to add the parameter `sub_type=organization` to the authorization URL: + + The default value of `sub_type` is user. + + ``` https://polar.sh/oauth2/authorize?response_type=code&client_id=polar_ci_j3X95_MgfdSCeCd2qkFnUw&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=openid%20email&sub_type=organization ``` @@ -81,23 +111,12 @@ At this point, the user will be prompted to select one of their organization bef The rest of the flow remains unchanged. The access token you'll get will be tied to the selected organization. - -Bear in mind that some endpoints might not support organization access tokens. -Typically, user-specific endpoints like `/v1/users/benefit` will not work with -organization access tokens. - + + Some endpoints might not support organization access tokens. Typically, user-specific endpoints like `/v1/users/benefit` will not work with organization access tokens. + #### Public Clients Public clients are clients where the Client Secret can't be kept safe, as it would be accessible by the final user. This is the case for SPA, mobile applications, or any client running on the user's device. In this case, **and only if the client is configured as a Public Client**, the request to the token endpoint won't require the `client_secret` parameter. However, the [PKCE](https://oauth.net/2/pkce/) method will be required to maximize security. - -### Make authenticated requests - -Once you have an access token, either from a Personal Access Token or from the OpenID Connect flow, you can make authenticated requests to the API. Here is a simple example with cURL: - -```bash -curl -X GET https://api.polar.sh/v1/oauth2/userinfo \ - -H 'Authorization: Bearer polar_at_XXX' -``` diff --git a/docs/integrate/oauth2/introduction.mdx b/docs/integrate/oauth2/introduction.mdx index 7ff4e64cbd..f290574b72 100644 --- a/docs/integrate/oauth2/introduction.mdx +++ b/docs/integrate/oauth2/introduction.mdx @@ -4,13 +4,10 @@ sidebarTitle: "Introduction" description: "For partners building services and extensions for Polar customers" --- -### OpenID Connect (OAuth2) +### OpenID Connect (OAuth 2.0) Only use our **OpenID Connect** in case you want to act on the behalf of other users via our API, e.g building an app/service for Polar customers. Otherwise, always use an **Organization Access Token (OAT)** to integrate Polar for your own service. -Polar implements the [OpenID Connect specification](https://openid.net/developers/how-connect-works/) to enable third-party authentication. It's a layer on top of the OAuth2 framework aiming at making integration more standard and predictable. - -In particular, it comes with a **discovery endpoint** allowing compatible clients to automatically work with the OpenID Connect server. Here is Polar's one: - -[OpenID Configuration](https://api.polar.sh/.well-known/openid-configuration) +Polar implements the [OpenID Connect specification](https://openid.net/developers/how-connect-works/) to enable third-party authentication. It's a layer on top of the OAuth 2.0 framework aiming at making integration more standard and predictable. +In particular, it comes with a **discovery endpoint** allowing compatible clients to automatically work with the OpenID Connect server. Polar's OpenID Configuration is available at https://api.polar.sh/.well-known/openid-configuration. \ No newline at end of file diff --git a/docs/integrate/oauth2/setup.mdx b/docs/integrate/oauth2/setup.mdx index faf0cc2754..cc93c466f0 100644 --- a/docs/integrate/oauth2/setup.mdx +++ b/docs/integrate/oauth2/setup.mdx @@ -3,23 +3,50 @@ title: "Create an OAuth 2.0 Client" sidebarTitle: "Create a client" --- -Before being able to make authentication requests, you'll need an **OAuth2 Client**. It's the entity that'll identify you, as a third-party developer, between Polar and the final user. +To make authentication requests to Polar on behalf of your users, you will need an **OAuth 2.0 Client**. It's the entity that'll identify you, as a third-party developer, between Polar and the final user. -You can manage them from your [User Settings](https://polar.sh/settings#oauth) - -Here are the required fields: - -* *Application Name*: the name of the application that'll be shown to the final users. -* *Client Type*: the type of client you are creating. [Read more](#public-clients) -* *Redirect URIs*: for security reasons, you need to declare your application URL where the users will be redirected after granting access to their data. - - When configuring your OAuth client, you must use an `https://` URL for security reasons. We block `http://` URLs, except when the hostname is `localhost`. This exception allows you to use `http://localhost` for convenient testing in development mode. - -* *Scopes*: the list of scopes your app will be able to ask for. To improve privacy and security, select only the scopes you really need for your application. -* *Homepage URL*: the URL of your application. It'll be shown to the final users on the authorization page. - -Optionally, you can also add a **logo**, **terms of service** and **privacy policy** URL. They'll all be shown to the final users on the authorization page. - -Once your client is created, you'll get a **Client ID** and a **Client Secret**. You'll need those values to make authentication requests. - -Those values are super sensitive and should be kept secret. They allow making authentication requests on Polar! + + + Go to [Account Settings > Developer > OAuth Applications](https://polar.sh/dashboard/account/developer) and click the `New OAuth App` button to start obtaining the OAuth 2.0 `client_id` and `client_secret` values. + + + + + + Name of the application that will be shown to the final users. + + + Upload a logo to be shown on the authorization screen. + + + `Confidential Client` or `Public Client` + + + URL(s) where the users will be redirected after granting access to their data. + + When configuring your OAuth client, you must use an `https://` URL for security reasons. We block `http://` URLs, except when the hostname is `localhost`. This exception allows you to use `http://localhost` for convenient testing in development mode. + + + + + + The list of scopes your app will be able to ask for. + + + URL of your application. It will be shown to the final users on the authorization page. + + + URL to your application's terms of service. + + + URL to your application's privacy policy. + + + + Click the `Create` button to save the OAuth 2.0 configuration + + + Once the OAuth 2.0 configuration is saved, you will be presented with the `Client ID` and `Client Secret`. Store them as `client_id` and `client_secret` in your application as environment variables so that they can be securely accessed. + + +