---
updatedAt: 2025-06-20T23:48:49.000Z
agentTools:
  projectIndex: https://docs.sinai.com/llms.txt
---

# Accessing the API

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

| Parameter       | Description                                           |
| :-------------- | :---------------------------------------------------- |
| `grant_type`    | Must be `client_credentials`                          |
| `client_id`     | Your application's client ID                          |
| `client_secret` | Your application's client secret                      |
| `scope`         | (Optional) Space-separated list of scopes (see below) |

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

| Scope                                           | Grants access to                            |
| :---------------------------------------------- | :------------------------------------------ |
| `https://api.sinai.com/organization`            | Organization-level data and features        |
| `https://api.sinai.com/carbon_accounting`       | Read/write access to carbon accounting data |
| `https://api.sinai.com/baseline_forecasts`      | Baseline forecasts management               |
| `https://api.sinai.com/transition_plan`         | Transition plan modeling and access         |
| `https://api.sinai.com/reduction_projects`      | Emissions reduction project data            |
| `https://api.sinai.com/decarbonization_roadmap` | Strategic decarbonization roadmap           |

You may request multiple scopes by separating them with spaces.

Example request:

```curl
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:

```json
{
  "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:

```http
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:

```curl
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:

| Name            | Description                               |
| :-------------- | :---------------------------------------- |
| `response_type` | Must be `code`                            |
| `client_id`     | Your application's Client ID              |
| `redirect_url`  | Must match one registered with the client |
| `state`         | Optional CSRF protection token            |

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

```curl
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:

```curl
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:

```json
{
  "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:

```http
Authorization: Bearer eyJ...abc
```

### Refreshing the token

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

```curl
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.