# Authentication

InstaCharts offers an API that is meant to be used by third party apps, server to server. It is secured using the OAuth 2.0 Authorization Code Grant method.

Base URL: `https://api.instacharts.io/v1/oauth`

## Overview

The Authorization Code Grant flow is designed for applications that can securely store client credentials. This flow provides a higher level of security by exchanging an authorization code for an access token.

## Flow Sequence

1. Application redirects user to authorization endpoint
2. User grants permissions
3. Authorization server redirects back with authorization code
4. Application exchanges code for access token
5. Application uses access token to access protected resources

## Endpoints

### 1. Authorization Request

```
GET /authorize
```

Redirect users to this endpoint to initiate the authorization flow.

#### Query Parameters

| Parameter       | Required | Description                                             |
|-----------------|----------|---------------------------------------------------------|
| `client_id`     | Yes      | Your application’s client ID                            |
| `redirect_uri`  | Yes      | URI to redirect back to after authorization              |
| `response_type` | Yes      | Must be set to `code`                                  |
| `scope`         | No       | Space-separated list of permissions (e.g., `read write`)|
| `state`         | Yes      | Random string to prevent CSRF attacks                   |

#### Example Authorization URL

```
https://api.instacharts.io/v1/oauth/authorize?

client_id=your_client_id

&redirect_uri=https://your-app.com/callback

&response_type=code

&scope=read write

&state=xyz123
```

#### Success Response

Users will be redirected to your `redirect_uri` with:

```
HTTP/1.1 301 Redirect

Location: https://your-app.com/callback?code=AUTH_CODE_HERE&state=xyz123
```

#### Error Response

```
HTTP/1.1 301 Redirect

Location: https://your-app.com/callback?error=access_denied&error_description=User+denied+access&state=xyz123
```

### 2. Token Exchange

```
POST /token
```

Exchange the authorization code for an access token.

#### Request Headers

| Header           | Value                                   |
|------------------|-----------------------------------------|
| `Content-Type`   | `application/x-www-form-urlencoded`    |
| `Authorization`  | `Basic base64(client_id:client_secret)` |

#### Request Body Parameters

| Parameter       | Required | Description                                               |
|-----------------|----------|-----------------------------------------------------------|
| `grant_type`    | Yes      | Must be `authorization_code`                              |
| `code`          | Yes      | The authorization code received from the previous step    |
| `redirect_uri`  | Yes      | Must match the redirect URI used in step 1                |

#### Example Token Request

```
curl -X POST https://api.instacharts.io/v1/oauth/token \

-H "Authorization: Basic base64(client_id:client_secret)" \

-H "Content-Type: application/x-www-form-urlencoded" \

-d "grant_type=authorization_code" \

-d "code=AUTH_CODE_HERE" \

-d "redirect_uri=https://your-app.com/callback"
```

#### Success Response

```
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5...",
    "token_type": "Bearer",
    "expires_in": 7200,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5...",
    "scope": "read write"
}
```

#### Error Response

```
{
    "error": "invalid_grant",
    "error_description": "Authorization code is invalid or expired"
}
```

## Error Codes

| Error Code          | Description                                                     |
|---------------------|-----------------------------------------------------------------|
| `invalid_request`   | Missing required parameter or malformed request                  |
| `invalid_client`    | Client authentication failed                                     |
| `invalid_grant`     | Authorization code is invalid or expired                        |
| `invalid_scope`     | Requested scope is invalid or exceeds granted scope               |
| `unauthorized_client`| Client not authorized for this grant type                       |
| `server_error`      | Internal server error                                           |

## Security Requirements

1. All requests MUST use HTTPS
2. Authorization codes are single-use and expire after 10 minutes
3. The `redirect_uri` must exactly match the one registered with your application
4. Always validate the `state` parameter to prevent CSRF attacks
5. Store tokens securely server-side
6. Never expose tokens in URLs or client-side code