Setup and Authorization

FreJun provides two ways to authenticate your application:

1. OAuth 2.0 - Standard OAuth flow for third-party applications
2. API Key - Simple authentication using an API key

OAuth 2.0 Authentication

FreJun supports the OAuth 2.0 standard for authorizing third-party applications.

To get started:

1. Visit https://product.frejun.com and log in.
2. Navigate to the Settings section.
3. Go to the Developer tab.
4. Click on your existing OAuth app, or select Create App to register a new one.

Once your app is created, you’ll be redirected to a page displaying your Client ID and Client Secret.

Use these credentials to:

• Generate access and refresh tokens for authenticating with FreJun APIs.
• Subscribe to FreJun webhooks.

Requirements

1. An active Frejun account.
2. The following details are required while creating the app.

Parameter	Description
Name	Name of your App
Redirect/Callback URI	Users will be redirected to this URL after granting access to your app

Tip

You can use our OAuth SDK to simplify the OAuth flow in your application. The SDK provides helper functions to generate the authorization URL, exchange authorization codes for tokens, and manage token refreshes.

Connecting your application with FreJun

1. Build the Authorization URL with your application’s client_id and redirect the user there. It should look like this:
   https://product.frejun.com/oauth/authorize/?client_id=<client_id>

Note

You can append extra query parameters to the authorization URL. These parameters will be preserved and passed back as-is to the specified redirect_uri, for example:

https://product.frejun.com/oauth/authorize/?client_id=<client_id>&redirect_uri=<your_new_redirect_uri>&state=<your_custom_state>&username=<some_username>

After successful authentication, the user will be redirected to:

<redirect_url>?code=<oauth_code>&email=<user_email>&state=<your_custom_state>&username=<some_username>

2. Once the user reaches the Authorization page, they will be prompted to log in to FreJun (if not logged in already) and will be redirected to a consent page where they can Accept or Decline.
3. On Accepting, the user will be redirected to the redirect URL provided while creating the app with code and email of the user attached as a query param: <redirect_url>?code=<authorization_code>&email=<user_email>

Tip

Instead of always relying on the fixed redirect URI configured at the time of app creation, you can make it dynamic by passing it as a query parameter in the authorization URL, for example:

https://product.frejun.com/oauth/authorize/?client_id=<client_id>&redirect_uri=<your_new_redirect_uri>

4. On Declining, the user will be redirected to the redirect URL provided while creating the app with code attached as an empty string: <redirect_url>?code=
5. The code obtained can be used to create Access & Refresh tokens by invoking the create token endpoint.

Note

The authorization code is only valid for 10 minutes.

We also post a message back to the opener of the consent window containing the code and any other parameters that are appended to the redirect_uri, so the opener can directly consume the data without relying only on the redirect flow.

Example (listening for it on the opener side):

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://product.frejun.com' || !event.data) return; // to make sure the message you are listening to is from the expected origin
  let eventData = event.data;
  if(eventData.eventName == "oauth-code") {
    // Handle the oauth-code event
    const { code, email, ...otherparams } = eventData.data;
  }
});

In the above example:

code: The OAuth authorization code, which can be exchanged for access and refresh tokens.

email: The email address of the user who authorized the app via their Frejun account.

otherparams: Any additional parameters that were included in the original authorization URL.

Email Query Parameter

When making API requests using OAuth 2.0 authentication, the email query parameter is required and should be included in all API requests:

GET https://api.frejun.com/api/v2/endpoint?email=user@example.com
Authorization: Bearer <access_token>

The email should correspond to the user performing the action.

Tip

If the email query parameter is excluded when using OAuth 2.0 authentication, the Owner or Admin of the FreJun account will be used as the default user performing the action. If multiple owners or admins are present, any of them will be used.

API Key Authentication

API Key authentication provides a simpler alternative to OAuth 2.0 for authenticating API requests. This method is ideal for server-to-server integrations or internal applications.

Getting Your API Key

To create an API key:

1. Log in to your FreJun account at https://product.frejun.com
2. Navigate to Settings
3. Go to the Developer tab
4. Scroll to the bottom of the page to the API Key section
5. Click Create to generate a new API key

Using API Key in Requests

To authenticate using an API key, include it in the request header with the Api-Key prefix:

Authorization: Api-Key <your_api_key>

Email Query Parameter

When making API requests, you should pass the email query parameter to specify which user is performing the action:

GET https://api.frejun.com/api/v2/endpoint?email=user@example.com

Tip

If the email query parameter is excluded when using API Key authentication, the creator of the API key will be used as the default user performing the action.