General

The API is available at: https://api.sinai.com/v1

The OpenAPI specification is available at: https://developers.sinai.com/openapi.yaml.

Authentication

The HTTP API supports the OAuth 2.0 authorization framework, including the Authorization Code and Client Credentials flows.

Client Credentials

This is a machine-to-machine (M2M) authentication mechanism where your application obtains a token directly from the token endpoint by presenting its client credentials.

Getting an access token

Token endpoint:https://auth.sinai.com/oauth2/token

Send a POST request with the following parameters in application/x-www-form-urlencoded format:

You can request access to one or more of the following scopes depending on your integration needs:

You may request multiple scopes by separating them with spaces.

Example request:

curl --request POST \
  --url 'https://auth.sinai.com/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=https://api.sinai.com/carbon_accounting https://api.sinai.com/organization'

Example response:

{
  "access_token": "eyJraWQiOiJrMm...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Using the access token:

Once you have the access_token, include it in the Authorization header of each request to the SINAI API:

Authorization: Bearer YOUR_ACCESS_TOKEN

Authorization Code

This flow is ideal for applications that access the API on behalf of users and require secure delegated access.

Overview of the Flow

The Authorization Code Flow involves 3 key steps:

1. Redirect the user to authorize access
2. Receive an authorization code
3. Exchange the authorization code for an access token

Authorization Server Endpoints

Authorization URL: https://auth.sinai.com/oauth2/authorize

Token URL: https://auth.sinai.com/oauth2/token

Scopes: Currently no scopes are supported - access authorization is performed based on the related user's access configured within the SINAI platform.

Step-by-Step Guide

Step 1: Redirect User for Authorization

Redirect the user to the authorization URL with the following parameters:

GET https://auth.sinai.com/oauth2/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REDIRECT_URI
&state=SOME_RANDOM_STRING

Parameters:

Step 2: Handle Redirect with Authorization Code

Once the user approves access, the SINAI authorization server will redirect to your redirect_uri with the following parameters:

https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=SOME_RANDOM_STRING

You should now extract the code from the query string.

Step 3: Exchange Authorization Code for Access Token

Make a POST request to the token endpoint:

POST https://auth.sinai.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

Request body:

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=YOUR_REDIRECT_URI
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Response:

{
  "access_token": "eyJ...abc",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def...xyz"
}

Using the access token

Include the token in the Authorization header of API requests:

Authorization: Bearer eyJ...abc

Refreshing the token

Use the refresh token to obtain a new access token when the current one expires:

POST https://auth.sinai.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

Request body:

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Best practices

• Store access_token securely and avoid exposing it in frontend code.
• Always validate the state parameter when handling the redirect.
• Handle token expiration by using expires_in and implement auto-refresh.
• Use secure HTTPS connections for all OAuth requests.