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
The client identifier from your application (provided by Sendoso).
Client’s redirection endpoint previously established with the authorization server during the client registration process.
Value MUST be set to “code”.
The scope of the access request as described below.
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.
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
Value MUST be set to “authorization_code”.
The authorization code you just received
The same redirect URI that you initiated the flow with.
The client identifier from your application (provided by Sendoso).
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
}
The access token issued by the authorization server.
The type of the token issued. Value will ALWAYS be “bearer”.
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)
The refresh token, which can be used to obtain new access tokens using the same authorization grant
The scope(s) granted to this specific token.
Timestampt 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:
Value MUST be set to “refresh_token”.
The refresh token associated to the access token that you want to refresh.
The client identifier from your application (provided by Sendoso).
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
}
The new access token issued by the authorization server.
The type of the token issued. Value will ALWAYS be “bearer”.
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)
The new refresh token, which can be used to obtain new access tokens using the same authorization grant
The scope(s) granted to this specific token.
Timestampt when the new token was created in the authorization server. Could be used to calculate when the token is set to 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:
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:
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'