Authentication

Overview

The Finscreener API uses a two-step authentication process:

API Key Exchange: Exchange your API key for JWT tokens
Bearer Token: Use the JWT access token for all subsequent API calls

API keys start with fsk_ and can be obtained from your User Profile → Security settings.

Authentication Flow

Exchange your API key for JWT tokens:

curl -X POST https://api.finscreener.in/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"api_key": "fsk_your_api_key_here"}'

Response:

{
  "success": true,
  "message": "Login successful",
  "user": {
    "name": "John Doe",
    "userId": "usr_1e6f3517748c4923b90e1f3422967661c",
    "email": "john@example.com",
    "is_admin": false,
    "is_staff": false
  },
  "token": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer"
  }
}

The access_token expires after approximately 1 hour. Store the refresh_token securely to obtain new access tokens.

Step 2: Use Bearer Token

Include the access token in all API requests:

curl https://api.finscreener.in/api/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Your fsk_ API key is not a bearer token. It cannot be sent as Authorization: Bearer fsk_... — it must be exchanged at POST /api/auth/login first, and the token to send is the nested token.access_token (not a top-level access_token).Sending the raw key returns 401:

{
  "message": "You sent your API key as the Bearer token. Exchange it for an access token first: POST /api/auth/login with {\"api_key\": \"fsk_...\"}, then send the returned token.access_token as 'Authorization: Bearer <access_token>'."
}

Step 3: Refresh Access Token

When your access token expires, use the refresh token to get a new one:

curl -X POST https://api.finscreener.in/api/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJIUzI1NiIs..."}'

Error Handling

Status Code	Error	Description
400	Bad Request	Invalid request body or missing API key
401	Unauthorized	Invalid or expired token
403	Forbidden	Token not authorized for developer API
403	Account Suspended	Account has been suspended — contact support
429	Rate Limited	Too many login attempts — wait and retry

Best Practices

Secure Storage

Store API keys in environment variables, not in code
Never commit API keys to version control
Use secret management services in production

Token Management

Cache the access token and reuse until expiration
Implement automatic token refresh before expiration
Store refresh tokens securely (encrypted at rest)

Error Handling

Handle 401 errors by refreshing the token
Implement exponential backoff for rate limit errors (429)
Log authentication failures for debugging

Getting Started

Platform Guide

FQL Query Language

Classification Guide

Integrations

Changelog

Overview

Authentication Flow

Step 2: Use Bearer Token

Step 3: Refresh Access Token

Error Handling

Best Practices

​Overview

​Authentication Flow

​Step 1: Login with API Key

​Step 2: Use Bearer Token

​Step 3: Refresh Access Token

​Error Handling

​Best Practices

Overview

Authentication Flow

Step 1: Login with API Key

Step 2: Use Bearer Token

Step 3: Refresh Access Token

Error Handling

Best Practices