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 /api/scim/v2/Users endpoint, you would include the following header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Registering your application

In order to start using the SCIM API, you’ll need a client id and client secret specific for the SCIM API. 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

Value MUST be set to scim.

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.

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

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:

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

SCIM Reference

Authentication & Authorization

Introduction

Registering your application

Authorization Flow

1. Direct user to authorization endpoint

2. Authorization granted

3. Exchange code for access token

Refresh token

Revoke access token

Getting Started

SCIM Reference

​Introduction

​Registering your application

​Authorization Flow

​1. Direct user to authorization endpoint

​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

2. Authorization granted

3. Exchange code for access token

Refresh token

Revoke access token