Authentication
The API uses OAuth 2.0 bearer tokens. You create a long-lived refresh token once in the AlphaSense web app. Your code exchanges it for a short-lived access token and sends that token with every request.
1. Get your credentials
- Sign in to research.alpha-sense.com.
- Open Preferences, then API Keys.
- Copy the Client ID and Client Secret.
- Click Generate Refresh Token, confirm your identity, and copy the new token.
Copy the token itself, not the Refresh Token ID. The Expires At column shows when it stops working. The SuperAnalyst API does not use the API Key value on that page.
If you don't see the API Keys page, ask your account team to enable API access, SuperAnalyst, and SuperAnalyst API access for your user.
2. Get an access token
Send your credentials to the token endpoint as a form:
POST https://auth.research.alpha-sense.com/oauth/token
- Python
- JavaScript
- cURL
import os
import requests
response = requests.post(
"https://auth.research.alpha-sense.com/oauth/token",
data={
"grant_type": "refresh_token",
"client_id": os.environ["ALPHASENSE_CLIENT_ID"],
"client_secret": os.environ["ALPHASENSE_CLIENT_SECRET"],
"refresh_token": os.environ["ALPHASENSE_REFRESH_TOKEN"],
},
)
response.raise_for_status()
access_token = response.json()["access_token"]
const response = await fetch('https://auth.research.alpha-sense.com/oauth/token', {
method: 'POST',
body: new URLSearchParams({
grant_type: 'refresh_token',
client_id: process.env.ALPHASENSE_CLIENT_ID,
client_secret: process.env.ALPHASENSE_CLIENT_SECRET,
refresh_token: process.env.ALPHASENSE_REFRESH_TOKEN,
}),
})
if (!response.ok) throw new Error(`Token request failed: ${response.status}`)
const {access_token: accessToken} = await response.json()
curl -sS -X POST "https://auth.research.alpha-sense.com/oauth/token" \
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "client_id=$ALPHASENSE_CLIENT_ID" \
--data-urlencode "client_secret=$ALPHASENSE_CLIENT_SECRET" \
--data-urlencode "refresh_token=$ALPHASENSE_REFRESH_TOKEN"
The response looks like this:
{"access_token": "<access token>", "token_type": "Bearer", "expires_in": 1800}
The access token lasts expires_in seconds, about 30 minutes. The response can also include a new
refresh_token. When it does, the new one replaces your old one: save it and use it next time.
If the request fails, check your credentials before you try again. Repeated attempts with a wrong client secret can lock the client out.
An access token from the Agent API password grant also works with the SuperAnalyst API. For new integrations, use the refresh token flow above: it needs no password or API key.
3. Call the API
Send the access token in the Authorization header. No other auth headers are needed.
curl -sS "https://api.research.alpha-sense.com/superanalyst/v1/superanalysts/default/sessions?limit=1" \
-H "Authorization: Bearer $ACCESS_TOKEN"
A 200 response means your token and entitlements work.
Keep tokens fresh
In a long-running service, cache the access token and renew it shortly before it expires. Renew one request at a time. Parallel renewals all spend the same refresh token, and a rotated refresh token works only once.
- Python
- JavaScript
import os
import threading
import time
import requests
class TokenProvider:
def __init__(self):
self._refresh_token = os.environ["ALPHASENSE_REFRESH_TOKEN"]
self._access_token = None
self._expires_at = 0.0
self._lock = threading.Lock()
def headers(self):
with self._lock:
if time.time() > self._expires_at - 60:
self._renew()
return {"Authorization": f"Bearer {self._access_token}"}
def _renew(self):
response = requests.post(
"https://auth.research.alpha-sense.com/oauth/token",
data={
"grant_type": "refresh_token",
"client_id": os.environ["ALPHASENSE_CLIENT_ID"],
"client_secret": os.environ["ALPHASENSE_CLIENT_SECRET"],
"refresh_token": self._refresh_token,
},
)
response.raise_for_status()
token = response.json()
self._access_token = token["access_token"]
self._expires_at = time.time() + token["expires_in"]
# Also store a rotated refresh token in your secret store.
self._refresh_token = token.get("refresh_token", self._refresh_token)
class TokenProvider {
#refreshToken = process.env.ALPHASENSE_REFRESH_TOKEN
#accessToken = null
#expiresAt = 0
#renewal = null
async headers() {
if (Date.now() > this.#expiresAt - 60_000) {
this.#renewal ??= this.#renew().finally(() => (this.#renewal = null))
await this.#renewal
}
return {Authorization: `Bearer ${this.#accessToken}`}
}
async #renew() {
const response = await fetch('https://auth.research.alpha-sense.com/oauth/token', {
method: 'POST',
body: new URLSearchParams({
grant_type: 'refresh_token',
client_id: process.env.ALPHASENSE_CLIENT_ID,
client_secret: process.env.ALPHASENSE_CLIENT_SECRET,
refresh_token: this.#refreshToken,
}),
})
if (!response.ok) throw new Error(`Token request failed: ${response.status}`)
const token = await response.json()
this.#accessToken = token.access_token
this.#expiresAt = Date.now() + token.expires_in * 1000
// Also store a rotated refresh token in your secret store.
this.#refreshToken = token.refresh_token ?? this.#refreshToken
}
}
Call tokens.headers() before each request. An open stream keeps working after its token expires.
Entitlements
Each API user needs SuperAnalyst and SuperAnalyst API access. Without either one, requests
return 403 ENTITLEMENT_REQUIRED. Your account team enables both, and a change can take a few
minutes to apply.
Each user sees only their own sessions and files. Another user's session returns 404.
When authentication fails
| What you see | Cause | Fix |
|---|---|---|
access_denied from the token endpoint | Wrong client ID or secret | Stop. Re-copy both from the API Keys page, then try once. |
invalid_grant from the token endpoint | Refresh token expired, revoked, or rotated | Generate a new refresh token on the API Keys page. |
401 UNAUTHENTICATED from the API | Access token missing, expired, or invalid | Get a new access token. Send Authorization: Bearer <token>. |
403 ENTITLEMENT_REQUIRED from the API | An entitlement is missing | Ask your account team to enable it. |
The API does not say why it rejected a token. If a fresh token still gets 401, contact support
with the request_id from the error.
Keep credentials safe
- Load secrets from environment variables or a secrets manager. Never commit them.
- Never log tokens. Log the
request_idinstead. - If a refresh token leaks, generate a new one and stop using the old one.