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.

Tip

Prefer no code? The Zapier integration connects InstaCharts to thousands of apps without calling the API directly.

Note

Today, the API’s OAuth client is registered for the official Zapier integration. If you’re building your own third-party integration, contact support@instacharts.io for API access.

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:chart write:chart)
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:chart write:chart
    &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

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
client_id	Yes	Your application’s client ID
client_secret	Yes	Your application’s client secret

Note

Client credentials are sent as body parameters, not as an Authorization: Basic header.

Example Token Request

curl -X POST https://api.instacharts.io/v1/oauth/token \
    -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" \
    -d "client_id=your_client_id" \
    -d "client_secret=your_client_secret"

Success Response

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

Error Response

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

3. Refresh Token

POST /refresh

Exchange a refresh_token (returned from the token exchange above) for a new access token, without sending the user through the authorization flow again. Refresh tokens expire 90 days after they’re issued.

Request Body Parameters

Parameter	Required	Description
grant_type	Yes	Must be refresh_token
refresh_token	Yes	The refresh token to exchange
client_id	Yes	Your application’s client ID
client_secret	Yes	Your application’s client secret

The success and error response shapes match the Token Exchange endpoint above.

4. Validate Token

GET /validate

Send Authorization: Bearer YOUR_ACCESS_TOKEN to check whether a token is still valid. Returns:

{
    "active": true,
    "scope": "read:chart write:chart",
    "client_id": "your_client_id",
    "exp": 1735689600
}

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
unsupported_grant_type	The grant_type value isn’t recognized

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

Related

• Generate Image API - render a chart image once you have a token
• Templates API - list and use your chart templates
• Zapier Integration - automate charts without writing code