Skip to main content

​
Overview

The Finscreener API uses a two-step authentication process:
  1. API Key Exchange: Exchange your API key for JWT tokens
  2. 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

​
Step 1: Login with API Key

Exchange your API key for JWT tokens: 
curl -X POST https://api.finscreener.in/api/auth/api-key/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"
  },
  "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..."

​
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 CodeErrorDescription
400Bad RequestInvalid request body or missing API key
401UnauthorizedInvalid or expired token
403ForbiddenToken not authorized for developer API

​
Best Practices

  • Store API keys in environment variables, not in code
  • Never commit API keys to version control
  • Use secret management services in production
  • Cache the access token and reuse until expiration
  • Implement automatic token refresh before expiration
  • Store refresh tokens securely (encrypted at rest)
  • Handle 401 errors by refreshing the token
  • Implement exponential backoff for rate limit errors (429)
  • Log authentication failures for debugging