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