Developer Apps Guide

Safsira developer apps are OAuth 2.0 applications that you can create to authenticate and authorize yourself or your users to make requests to the Safsira API.

This guide will take you through the process of creating OAuth 2.0 applications within the Safsira dashboard, as well as how to use them to request products, add recipients, place orders, and generate shipping orders.

ℹ️

This guide assumes you have some understanding of OAuth 2.0 flow. Please refer to these resources for a more comprehensive understanding:

Creating Developer Apps in Safsira Dashboard

Sign up for an account

ℹ️

If you are using a Private app you must have an account set up with email and password (instead of Google or Microsoft). If you already have an account created using Google or Microsoft, you must sign up again using email and password. Using the same email, will allow the system to automatically link the accounts.

Create an app

Go to your Dashboard (opens in a new tab) and navigate to Developer Apps on the side bar. Here you will find a list of all your apps. Click on CREATE APP to create a new app.

Create new app

Specify app details

You will be prompted for several details about your app. These include the type, name, description, and logo (optional).

ℹ️

There are two types of apps: Private and Third-party. The difference between the two is explained in the next section.

Specify app details

After, clicking the CREATE button you will be redirected to the app settings page. There you will find the Client ID and Client Secret necessary for the OAuth 2.0 flow. Also, you will be allowed to set Allowed callback URLs.

Created app

Endpoints can be found by clicking on the Endpoints tab.

Endpoints information

Difference Between Private and Third-party Apps

We allow two types of apps: Private and Third-party. The difference between the two is in the way they are used and the permissions they have.

Private: Request the password grant type when requesting an access token. This means you will need to provide your Safsira account's username and password to get an access token. These apps can access and modify all resources tied to your Safsira account.

Third-Party: Request the authorization_code grant type and involves exchanging an authorization code for a token. This means you will need to redirect users to Safsira's authorization page where they can grant your app permissions. These apps can only access and modify resources within the scope granted by the user.

Getting an OAuth 2.0 Token

This section will provide the necessary information to get an access token using a Safsira Developer App to get access to the Safsira API.

Private Apps

Get the required information from your app

Go to your app settings page and copy your Client ID and Client Secret.

Request access token

Make a POST request to Safsira's token endpoint:

Token endpoint:

https://login.safsira.com/oauth/token

You must use the following headers:

{
    "Content-Type": "application/json"
}

Payload:

{
    "client_id": "<your_client_id>",
    "client_secret": "<your_client_secret>",
    "username": "<your_username>",
    "password": "<your_password>",
    "grant_type": "password",
    "scope": "openid profile offline_access email",
    "audience": "safsira"
}

Response:

{
    "access_token": "<access_token>",
    "refresh_token": "<refresh_token>",
    "id_token": "<id_token>",
    "scope": "openid profile email offline_access",
    "expires_in": 86400,
    "token_type": "Bearer"
}

In the response, you will get the access_token and refresh_token that you can use to make requests to the Safsira API. The access_token is valid for 24 hours. After that, you can use the refresh_token to get a new access_token.

Third-party Apps

For Third-party Apps, users are redirected to Safsira's authorization page where they can grant your app permissions:

https://login.safsira.com/authorize?client_id=<your_client_id>&response_type=code&redirect_uri=<your_redirect_uri>&scope=offline_access&audience=safsira

Once granted, they are redirected back to your app with an authorization code. This code can then be exchanged for an access token by making a POST request to Safsira's token endpoint:

{
  "client_id": "<your_client_id>",
  "client_secret": "<your_client_secret>",
  "grant_type": "authorization_code",
  "code": "<authorization_code>",
  "redirect_uri": "<your_redirect_uri>"
}

ℹ️

For a detailed guide on the Authorization Code grant flow, refer to:

[Authorization Code Grant](https://www.oauth.com/OAuth (opens in a new tab) 2.0-servers/server-side-apps/authorization-code/)
Authorization Code Flow (opens in a new tab)

Refreshing an Access Token

Refresh tokens are used to request a new access token for a user without requiring them to re-authenticate. Typically, you should request a new access token before the previous one expires (to avoid any service interruption)

To exchange the refresh token you received during authentication for a new access token, you need to do a POST request to Safsira's token endpoint:

Token endpoint:

https://login.safsira.com/oauth/token

Payload:

{
    "client_id": "<your_client_id>",
    "client_secret": "<your_client_secret>",
    "refresh_token": "<refresh_token>",
    "grant_type": "refresh_token"
}

Response:

{
    "access_token": "<access_token>",
    "id_token": "<id_token>",
    "scope": "openid profile email offline_access",
    "expires_in": 86400,
    "token_type": "Bearer"
}

The response will include a new access_token, its type, its lifetime (in seconds), and the granted scopes.

Walkthrough Product Design and Ordering Webhook Subscriptions