Authentication & Authorization

Introduction

Sendoso follows the standard OAuth 2.0 spec, using the Authorization Code grant type. OAuth is an open standard for access delegation, commonly used as a way for Internet users to grant websites or applications access to their information on other websites but without giving them the passwords. This is known as a “two-legged” OAuth, or “two-step” authentication process. Refer to the OAuth 2.0 Authorization Framework RFC: Section 4.1 for additional details.

To authenticate with the Sendoso API using OAuth, you will need to first register your application and obtain a client ID and client secret. You can then use these credentials to request an access token from the Sendoso OAuth endpoint.

Once you have an access token, you can include it in the Authorization header of your API requests. For example, to make a GET request to the GET /sends endpoint, you would include the following header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Registering your application

In order to start using the API, you’ll need a client id and client secret. You can obtain those by contacting our support at developers@sendoso.com

Authorization Flow

1. Direct user to authorization endpoint

The first step of the flow is to direct the user to the authorization endpoint providing as URL parameters its client identifier, requested scope, local state, and a redirection URI to which the authorization server will send the user-agent back once access is granted.

https://app.sendoso.com/oauth/authorize

client_id

string

required

The client identifier from your application (provided by Sendoso).

redirect_uri

string

required

Client’s redirection endpoint previously established with the authorization server during the client registration process.

response_type

string

required

Value MUST be set to “code”.

scope

string

The scope of the access request as described below.

state

string

An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery.

Permission scopes

Sendoso’s API supports the use of permissions scopes to specify the level of access that your application is requesting for a user’s account. Scopes are used to grant access to specific resources or actions within the Sendoso platform. When a user grants your application access to their account, they will also be prompted to grant specific scopes of access.

The available scopes for Sendoso API are:

public: Allows your application to access the user’s basic information.
write: Allows your application to send gifts on the user’s behalf.
update: Allows your application to update the user’s account details.
marketplace: Allows your application to access the marketplace api.
smartsend: Allows your application to access the smartsend api.

To request specific scopes, you can include them as a space-separated list in the scope parameter of the OAuth authorization request. For example, to request access to send gifts and to update user’s account details, you would include the following scope parameter:

scope=write update

Please note that the user must grant your application access to each scope individually.

2. Authorization granted

After the user logs in and grants access to your application they will be redirected to the redirect URI specified in the previous step along with an authorization code as parameter named code.

3. Exchange code for access token

Once you have the code after the user granted access to your application, you need to exchange this code for an access token by making a POST to the endpoint and the body below:

https://app.sendoso.com/oauth/token

grant_type

string

required

Value MUST be set to “authorization_code”.

code

string

required

The authorization code you just received

redirect_uri

string

required

The same redirect URI that you initiated the flow with.

client_id

string

required

The client identifier from your application (provided by Sendoso).

client_secret

string

required

The client secret from your application (provided by Sendoso).

The server will respond with an access token and a refresh token as follows:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"bearer",
  "expires_in":7200,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "scope":"public"
  "created_at":1693513711
}

access_token

string

required

The access token issued by the authorization server.

token_type

string

required

The type of the token issued. Value will ALWAYS be “bearer”.

expires_in

string

required

The lifetime in seconds of the access token. Value will ALWAYS be “7200”. It denotes that the access token will expire in 2 hours from the time the token was created (see created_at)

refresh_token

string

required

The refresh token, which can be used to obtain new access tokens using the same authorization grant

scope

string

required

The scope(s) granted to this specific token.

created_at

string

required

Timestamp when the token was created in the authorization server. Could be used to calculate when the token is set to expire.

You will need to use the access token in the Authorization header of your API requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

Refresh token

Please note that access tokens have a limited lifespan of 7200 seconds (2 hours) and will need to be refreshed.

To refresh your OAuth access token, you will need to make a POST request to the Sendoso OAuth token refresh endpoint:

https://app.sendoso.com/oauth/token

You will need to include the following parameters in the request body:

grant_type

string

required

Value MUST be set to “refresh_token”.

refresh_token

string

required

The refresh token associated to the access token that you want to refresh.

client_id

string

required

The client identifier from your application (provided by Sendoso).

client_secret

string

required

The client secret from your application (provided by Sendoso).

The server will respond with a new access token and refresh token as follows:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"bearer",
  "expires_in":7200,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "scope":"public"
  "created_at":1693513711
}

access_token

string

required

The new access token issued by the authorization server.

token_type

string

required

The type of the token issued. Value will ALWAYS be “bearer”.

expires_in

string

required

The lifetime in seconds of the access token. Value will ALWAYS be “7200”. It denotes that the access token will expire in 2 hours from the time the token was created (see created_at)

refresh_token

string

required

The new refresh token, which can be used to obtain new access tokens using the same authorization grant

scope

string

required

The scope(s) granted to this specific token.

created_at

string

required

Timestampt when the new token was created in the authorization server. Could be used to calculate when the token is set to expire.

Refresh tokens do not expire

Revoke access token

In order to revoke access tokens (and their associated refresh token), you can make a POST request to the following endpoint and parameters:

https://app.sendoso.com/oauth/revoke

Headers:

Authorization

string

required

Basic authorization by base 64 encoding the application client id and client secret separated with ”:”. e.g. Basic ENCODED_CLIENT_ID_AND_SECRET where ENCODED_CLIENT_ID_AND_SECRET is the following operation Base64(client_id:client_secret).

Parameters:

token

string

required

The access token that you want to revoke.

For example:

curl --location \
  --request POST 'https://app.sendoso.com/oauth/revoke?token=YOUR_ACCESS_TOKEN' \
  --header 'Authorization: Basic ENCODED_CLIENT_ID_AND_SECRET'

Getting Started

API Reference

Authentication & Authorization

Introduction

Registering your application

Authorization Flow

1. Direct user to authorization endpoint

Permission scopes

2. Authorization granted

3. Exchange code for access token

Refresh token

Revoke access token

Getting Started

API Reference

​Introduction

​Registering your application

​Authorization Flow

​1. Direct user to authorization endpoint

​Permission scopes

​2. Authorization granted

​3. Exchange code for access token

​Refresh token

​Revoke access token

Introduction

Registering your application

Authorization Flow

1. Direct user to authorization endpoint

Permission scopes

2. Authorization granted

3. Exchange code for access token

Refresh token

Revoke access token