# Authentication

All requests to the Makini Unified API are authenticated using a **Bearer token** passed in the `Authorization` header. Each token is scoped to a single connection and grants access only to data from that connected system.

```bash
curl https://api.makini.io/v4/sites \
    -H "Authorization: Bearer CONNECTION_TOKEN"
```

Tokens expire and must be refreshed or regenerated when they do. There are three ways to obtain a connection token.

## Makini Link (OAuth 2.0)

Makini Link is an OAuth 2.0-based authentication flow designed for production use. It allows your end users to select a platform, enter their credentials, and authorize a connection — all without exposing credentials to your application.

### Prerequisites

Before using Makini Link, go to **Settings > Application Settings** in the dashboard to:

- Copy your **Client ID** and **Client Secret**.
- Configure one or more **Redirect URIs** — these are the URLs Makini will redirect to after the user completes authentication.

### How it works

1. Your application redirects the user to the Makini Link authorization URL.
2. The user selects a platform and enters their credentials.
3. On success, Makini redirects back to your redirect URI with an authorization code.
4. Your backend exchanges the authorization code for a connection token.

### Authorization request

Redirect the user to:

```
https://link.makini.io/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code
```

### Token exchange

After the user is redirected back with an authorization code, exchange it for a connection token:

```bash
curl -X POST https://api.makini.io/link/token \
    -H "Content-Type: application/json" \
    -d '{
        "grant_type": "authorization_code",
        "code": "AUTHORIZATION_CODE",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "redirect_uri": "YOUR_REDIRECT_URI"
    }'
```

The response includes an `access_token` and a `refresh_token`:

```json
{
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "eyJ0eXAiOiJSZWZy..."
}
```

Use the `access_token` as the Bearer token in API requests. When it expires, use the `refresh_token` to obtain a new one.

### Refreshing a token

```bash
curl -X POST https://api.makini.io/link/token \
    -H "Content-Type: application/json" \
    -d '{
        "grant_type": "refresh_token",
        "refresh_token": "YOUR_REFRESH_TOKEN",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET"
    }'
```

> This is the recommended method for production applications where your end users connect their own systems.

## Dashboard (Manual)

For development and testing, you can generate a token directly from the Makini dashboard.

1. Navigate to **Connections** in the left-side menu.
2. Find the connection you want a token for.
3. Click the **options menu** (⋯) on the right side of the connection row.
4. Select **Generate Token**.

The token is displayed once — copy it immediately. This method is best suited for local development, debugging, or quick testing against a specific connection.

## Admin API

You can also generate connection tokens programmatically using the Makini Admin API. This is useful for backend automation, CI/CD pipelines, or managing tokens across multiple connections without the dashboard.

See the [Admin API reference](./admin-api-authentication) for details.

## Token Expiration

Connection tokens expire. When a token expires, API requests return a `401 Unauthorized` response. Use the refresh token to obtain a new access token (see [Refreshing a token](#refreshing-a-token) above). If the refresh token has also expired, you will need to go through the full authorization flow again.

## API Versioning

Makini supports two API versions. You can select the version in **Settings > Application Settings**.

- **v4** (recommended) — Base URL: `https://api.makini.io/v4/{endpoint}`
- **v3** (legacy) — Limited support. Not recommended for new integrations.

All examples in this documentation use v4.