> ## Documentation Index
> Fetch the complete documentation index at: https://developer.sendoso.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://www.rfc-editor.org/rfc/rfc6749#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:

```js theme={null}
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](mailto: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.

```js theme={null}
https://app.sendoso.com/oauth/authorize
```

<ParamField path="client_id" type="string" required>
  The client identifier from your application (provided by Sendoso).
</ParamField>

<ParamField path="redirect_uri" type="string" required>
  Client's redirection endpoint previously established with the authorization server during the client registration process.
</ParamField>

<ParamField path="response_type" type="string" placeholder="code" required>
  Value MUST be set to `code`.
</ParamField>

<ParamField path="scope" type="string">
  Value MUST be set to `scim`.
</ParamField>

<ParamField path="state" type="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.
</ParamField>

### 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:

```js theme={null}
https://app.sendoso.com/oauth/token
```

<ParamField body="grant_type" type="string" required>
  Value MUST be set to `authorization_code`.
</ParamField>

<ParamField body="code" type="string" required>
  The authorization code you just received
</ParamField>

<ParamField body="redirect_uri" type="string" required>
  The same redirect URI that you initiated the flow with.
</ParamField>

<ParamField body="client_id" type="string" required>
  The client identifier from your application (provided by Sendoso).
</ParamField>

<ParamField body="client_secret" type="string" required>
  The client secret from your application (provided by Sendoso).
</ParamField>

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
}
```

<ResponseField name="access_token" type="string" required>
  The access token issued by the authorization server.
</ResponseField>

<ResponseField name="token_type" type="string" required>
  The type of the token issued. Value will ALWAYS be "bearer".
</ResponseField>

<ResponseField name="expires_in" type="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`)
</ResponseField>

<ResponseField name="refresh_token" type="string" required>
  The refresh token, which can be used to obtain new access tokens using the same authorization grant
</ResponseField>

<ResponseField name="scope" type="string" required>
  The scope(s) granted to this specific token.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  Timestampt when the token was created in the authorization server. Could be used to calculate when the token is set to expire.
</ResponseField>

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

```js theme={null}
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:

```js theme={null}
https://app.sendoso.com/oauth/token
```

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

<ParamField body="grant_type" type="string" required>
  Value MUST be set to "refresh\_token".
</ParamField>

<ParamField body="refresh_token" type="string" required>
  The refresh token associated to the access token that you want to refresh.
</ParamField>

<ParamField body="client_id" type="string" required>
  The client identifier from your application (provided by Sendoso).
</ParamField>

<ParamField body="client_secret" type="string" required>
  The client secret from your application (provided by Sendoso).
</ParamField>

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
}
```

<ResponseField name="access_token" type="string" required>
  The new access token issued by the authorization server.
</ResponseField>

<ResponseField name="token_type" type="string" required>
  The type of the token issued. Value will ALWAYS be "bearer".
</ResponseField>

<ResponseField name="expires_in" type="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`)
</ResponseField>

<ResponseField name="refresh_token" type="string" required>
  The new refresh token, which can be used to obtain new access tokens using the same authorization grant
</ResponseField>

<ResponseField name="scope" type="string" required>
  The scope(s) granted to this specific token.
</ResponseField>

<ResponseField name="created_at" type="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.
</ResponseField>

<Info>Refresh tokens only expire after they are used</Info>

## 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:**

<ParamField header="Authorization" type="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)`.
</ParamField>

**Parameters:**

<ParamField path="token" type="string" required>
  The access token that you want to revoke.
</ParamField>

For example:

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