Authentication
The public API uses Bearer Token (JWT). Sign in to get a token and send it with each request.
Bearer Token
Step 1: Sign In
curl -X POST https://dashboard.socialprofiler.com/api/v1/auth/signin \
-H "Content-Type: application/json" \
-d '{
"email": "your@email.com",
"password": "your_password",
"token": true
}'
Response:
{
"status": "success",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
The token field in the request body only controls whether the JWT is returned in the
response body. Sign-in also sets a session cookie regardless of token, so a browser client
that relies on the cookie can omit it.
remember sets how long the session lives. It defaults to true (the long session); send
"remember": false for a short session. A short session cannot be renewed after its token has
expired (see below).
Step 2: Use Token in Requests
curl https://dashboard.socialprofiler.com/api/v1/auth/info \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Token Lifetime and Refresh
JWTs are valid for a server-configured duration (24 hours in the current configuration). To get
a fresh token without re-sending the password, call POST /auth/token/refresh — it issues a new
JWT from the session cookie set at sign-in (works even after the previous JWT has expired, as
long as the session is still renewable):
curl -X POST https://dashboard.socialprofiler.com/api/v1/auth/token/refresh \
-H "Cookie: <session cookie from sign-in>"
Response: same shape as sign-in, {"status": "success", "token": "..."}.
The refresh is refused with 401 when:
- the session has no signed-in user (the cookie is missing, cleared or expired);
- the sign-in used
"remember": falseand the token has expired; - the account has the administrator role;
- the password was changed after the session started;
- the account was deleted;
- the session is older than its maximum lifetime (90 days).
After any of these, sign in again with the password. Calling POST /auth/signin again also works
at any time and is not deprecated.
Sign Up
curl -X POST https://dashboard.socialprofiler.com/api/v1/auth/signup \
-H "Content-Type: application/json" \
-d '{
"email": "your@email.com",
"password": "your_password",
"token": "<recaptcha-token>"
}'
Here token is a reCAPTCHA token string — required — not the boolean used by sign-in. Sign-up
is meant to be driven by a browser that can solve the challenge. Optional fields: promocode,
acquisition_code (see below) and analytics_event_id (a UUID the client generates to pair the
sign-up with its browser analytics event, so the two are counted once).
On success (200 OK, {"status": "success"}) the response does not contain a JWT in the
body, but the sign-up does sign the session in: the response sets the session cookie. Call
POST /auth/token/refresh with that cookie to get a token, or call POST /auth/signin with
"token": true.
A password longer than 72 bytes is refused with 400 bcrypt: password length exceeds 72 bytes.
When registration is turned off, sign-up answers 401 {"code": 401, "message": "Registration is disabled"}.
Public Endpoints
Some endpoints are public and do not require a token:
| Endpoint | Purpose |
|---|---|
POST /auth/signin | Sign in |
POST /auth/token/refresh | Refresh the JWT from the session cookie |
POST /auth/signup | Register a new account |
POST /auth/recovery | Request password recovery |
GET /auth/recovery/{hash} | Validate a recovery link |
POST /auth/recovery/{hash} | Complete password recovery |
POST /auth/confirm/{hash} | Confirm an account via an emailed link |
POST /auth/google | Google OAuth sign in |
GET /check/{reportId} | Report readiness (Bearer optional; the answer depends on who asks) |
GET /sse/{reportId} | Stream report updates (Bearer optional; the report must be readable by the caller) |
POST /auth/signout, GET /auth/info, and DELETE /auth/google require a Bearer token.
Google OAuth
For applications that want to offer "Sign in with Google":
curl -X POST https://dashboard.socialprofiler.com/api/v1/auth/google \
-H "Content-Type: application/json" \
-d '{
"clientId": "your_google_client_id",
"credential": "google_jwt_token",
"select_by": "user"
}'
Response:
{
"status": "success",
"isNewUser": false
}
isNewUser tells you whether this call created a new account or matched an existing one. Like
sign-in, the response body contains a JWT token only when the request also sets "token": true.
DELETE /auth/google (authenticated, Bearer required) unlinks the Google account from the
current user.
Attribution: acquisition_code (optional)
Both POST /auth/signup and POST /auth/google accept an optional acquisition_code string (max 256 chars) — a campaign / attribution marker captured from the landing page (e.g. utm_campaign, ref, src, acquisition cookie). It is independent of promocode and is persisted on the user record and forwarded to Stripe metadata on subscription events.
curl -X POST https://dashboard.socialprofiler.com/api/v1/auth/google \
-H "Content-Type: application/json" \
-d '{
"clientId": "your_google_client_id",
"credential": "google_jwt_token",
"select_by": "user",
"acquisition_code": "utm_campaign=spring_launch"
}'
Same field is accepted on /auth/signup alongside promocode.
Password Recovery
POST /auth/recoverywith{"email": "..."}— sends a recovery email to the address on file. The answer is{"status": "success"}whether or not an account exists for the address (an email is sent only to an existing account), so the answer never reveals which addresses are registered. The only refusal that depends on the caller alone is the per-session "requests too often" one, answered200with"status": "error"and anerrortext; a malformed address is afieldErroronemail.GET /auth/recovery/{hash}— validates that the recovery link (from the email) is still valid. An invalid or expired link answers200{"status": "error", "error": "Wrong or expired link"}.POST /auth/recovery/{hash}with{"password": "<new password>"}— sets the new password and signs the browser session in (the session cookie is set). The body carries no token; callPOST /auth/token/refreshwith that cookie, orPOST /auth/signin, to get one. An unknown, used, expired or claimed hash answers404{"code": 404, "message": "Wrong or expired link"}.
Account Confirmation
POST /auth/confirm/{hash} confirms the account using the hash from the confirmation email. No
request body. A wrong or expired hash answers 200
{"status": "error", "error": "Wrong or expired link"}. When the confirmation succeeds, every open
report stream of that user receives a confirm event.
Error Responses
Bad credentials on POST /auth/signin (unknown email, wrong password, deleted account, or a
malformed email address) are
reported as HTTP 401 with {"code": 401, "message": "user not found"}, the same body for every
case. This 401 means bad credentials, not an expired token: do not call /auth/token/refresh for
it.
On sign-up and recovery a malformed email address is a field error (see below); sign-in answers it with the same 401 as any other bad credentials.
A validation/authentication failure on POST /auth/signup, POST /auth/recovery,
POST /auth/recovery/{hash} and POST /auth/google is reported as HTTP 200 with a
fieldError, not as a 4xx status:
{
"status": "",
"fieldError": {
"field": "password",
"message": "wrong password"
}
}
Check fieldError, not status. On sign-up, Google sign-in and POST /auth/recovery/{hash}
the status is an empty string; only POST /auth/recovery, GET /auth/recovery/{hash} and
POST /auth/confirm/{hash} answer "status": "error". A malformed email ("bad email") is
{"fieldError": {"field": "email", "message": "bad email"}} with HTTP 200 and an empty status
on sign-up and recovery (sign-in answers 401). field is one of email, password or promocode. For a
bad/expired/exhausted promocode the message is always the generic "Promo code is invalid, expired or was used up to the limit." regardless of the specific reason.
401 Unauthorized with the general error shape is used for a missing, invalid, or expired
Bearer token / session on an endpoint that requires one — a different failure mode from the
field errors above. For an invalid or expired token the message is the token validator's text;
access denied is a guest session on a route that needs an account:
{
"code": 401,
"message": "access denied"
}
A call authenticated as an account that has been deleted answers 401 {"code": 401, "message": "account deleted"}.
403 Forbidden
{
"code": 403,
"message": "access denied"
}
Causes:
- Token valid but the report/resource belongs to another user
- Report already generated (see Error Handling)
Security Best Practices
- Never expose tokens in client-side code - Use server-side proxy for API calls
- Use HTTPS only - All API endpoints require HTTPS
- Store tokens securely - Use secure storage (Keychain, encrypted preferences)
- Handle token expiry - Call
POST /auth/token/refresh(needs the session cookie) or sign in again
Code Examples
JavaScript/Node.js
const axios = require('axios');
const API_BASE = 'https://dashboard.socialprofiler.com/api/v1';
// Sign in and get token
async function authenticate(email, password) {
const response = await axios.post(`${API_BASE}/auth/signin`, {
email,
password,
token: true
});
return response.data.token;
}
// Create authenticated client
function createClient(token) {
return axios.create({
baseURL: API_BASE,
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
}
});
}
// Usage
const token = await authenticate('user@example.com', 'password');
const client = createClient(token);
const userInfo = await client.get('/auth/info');
Python
import requests
API_BASE = 'https://dashboard.socialprofiler.com/api/v1'
def authenticate(email: str, password: str) -> str:
response = requests.post(f'{API_BASE}/auth/signin', json={
'email': email,
'password': password,
'token': True
})
response.raise_for_status()
return response.json()['token']
def create_session(token: str) -> requests.Session:
session = requests.Session()
session.headers.update({
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json'
})
return session
# Usage
token = authenticate('user@example.com', 'password')
session = create_session(token)
user_info = session.get(f'{API_BASE}/auth/info').json()
Go
package main
import (
"bytes"
"encoding/json"
"net/http"
)
const apiBase = "https://dashboard.socialprofiler.com/api/v1"
type SignInRequest struct {
Email string `json:"email"`
Password string `json:"password"`
Token bool `json:"token"`
}
type SignInResponse struct {
Status string `json:"status"`
Token string `json:"token"`
}
func authenticate(email, password string) (string, error) {
body, _ := json.Marshal(SignInRequest{
Email: email,
Password: password,
Token: true,
})
resp, err := http.Post(apiBase+"/auth/signin", "application/json", bytes.NewBuffer(body))
if err != nil {
return "", err
}
defer resp.Body.Close()
var result SignInResponse
json.NewDecoder(resp.Body).Decode(&result)
return result.Token, nil
}