OAuth 2.0 Connect

1. Redirect the user to Authorization URL

   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. The most important ones are:

   response_type=code · string · required

   Indicates that you want to use the authorization code flow. Most common and the only one supported by Polar.

   sub_type · string · default: "user" · required

   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.

   client_id · string · required

   The Client ID you got when creating the OAuth 2.0 client.

   redirect_uri · string · required

   The URL where the user will be redirected after granting access to their data. Make sure you declared it when creating the OAuth2 client.

   scope · string · required

   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.

2. Exchange authorization code 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. 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:

   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:

   {
     "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.

3. Make authenticated requests

   Once you have an access token, you can make authenticated requests to the API. Here is a simple example with cURL:

   curl -X GET https://api.polar.sh/v1/oauth2/userinfo \
     -H 'Authorization: Bearer polar_at_XXX'
   

User vs Organization Access Tokens

We support the concept of access tokens at organization level. Contrary to the standard access tokens, those tokens are not tied to a user but to an organization. They can be used to make requests operating only on a specific organization data, improving privacy and security.

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

At this point, the user will be prompted to select one of their organization before allowing access to their data.

The rest of the flow remains unchanged. The access token you’ll get will be tied to the selected organization.

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 method will be required to maximize security.