> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parsalink.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Authentication
> Authenticate with the ParsaLink API using JWT tokens or API keys.
Authentication
## Login
Exchange your email and password for a JWT access token and refresh token.
```http theme={null}
POST /api/auth/login/
```
**Request body:**
```json theme={null}
{
"email": "you@example.com",
"password": "your_password"
}
```
**Response:**
```json theme={null}
{
"access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMDFIWC4uLiIsImV4cCI6MTcxMTUwMzYwMH0...",
"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMDFIWC4uLiIsImV4cCI6MTcxNDA2NTYwMH0...",
"user": {
"id": "usr_01HX...",
"email": "you@example.com",
"firstName": "Jane",
"lastName": "Smith",
"workspaceId": "ws_01HX..."
}
}
```
The `access` token expires after **1 hour**. The `refresh` token expires after **30 days**.
***
Tokens
## Token Refresh
Use the refresh token to obtain a new access token without re-authenticating.
```http theme={null}
POST /api/auth/token/refresh/
```
**Request body:**
```json theme={null}
{
"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
**Response:**
```json theme={null}
{
"access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
If the refresh token has expired, you must log in again to get a new pair of tokens. Refresh tokens are rotated on each use — the old refresh token is invalidated when a new one is issued.
***
Usage
## Using the Access Token
Include the access token in the `Authorization` header of every API request:
```http theme={null}
GET /api/contacts/
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
***
API Keys
## API Key Authentication
For server-to-server integrations where storing user credentials is not ideal, ParsaLink supports workspace-level API keys.
### Creating an API Key
1. Go to **Settings → API Keys**.
2. Click **Create API Key**.
3. Give the key a name (e.g., "Zapier Integration" or "Internal Dashboard").
4. Copy the key — it is only shown once.
API keys are shown only at the time of creation. If you lose a key, you must revoke it and create a new one. Store keys securely in environment variables or a secrets manager — never in client-side code or version control.
***
Usage
### Using an API Key
API keys use the same `Authorization: Bearer` header format:
```http theme={null}
GET /api/contacts/
Authorization: Bearer pk_live_01HX...
```
API keys are scoped to the workspace, not to an individual user. Actions performed with an API key are attributed to a system user in activity logs.
***
Management
### Revoking an API Key
Go to **Settings → API Keys**, find the key, and click **Revoke**. The key stops working immediately.
***
Example
## Example: Full Authentication Flow
Example flow showing login, authenticated request, and token refresh.
```python theme={null}
import requests
# Step 1: Log in
response = requests.post("https://api.parsalink.io/api/auth/login/", json={
"email": "you@example.com",
"password": "your_password"
})
tokens = response.json()
access_token = tokens["access"]
refresh_token = tokens["refresh"]
# Step 2: Make an authenticated request
headers = {"Authorization": f"Bearer {access_token}"}
contacts = requests.get("https://api.parsalink.io/api/contacts/", headers=headers)
# Step 3: Refresh when token expires
new_tokens = requests.post("https://api.parsalink.io/api/auth/token/refresh/", json={
"refresh": refresh_token
})
access_token = new_tokens.json()["access"]
```
***
Security
## Security Best Practices
Follow these best practices to keep your API usage secure.
* **Never hardcode credentials** — Use environment variables for tokens and API keys.
* **Store refresh tokens securely** — Treat them like passwords.
* **Rotate API keys regularly** — Create a new key and revoke the old one periodically.
* **Use HTTPS only** — All API communication must be over TLS. HTTP is not supported.
* **Monitor key usage** — Review API key activity logs in **Settings → API Keys** to detect unauthorized access.