​
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'
Rate LimitsPagination