Authentication Guide

All SpeechLytics API endpoints (except the health check endpoint) require Bearer token authentication.

Obtaining a Token

Endpoint

POST /api/v1/auth/token

Request

Send your credentials to obtain an authentication token:

curl -X POST "https://api.example.com/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "Username": "your_username",
    "Password": "your_password"
  }'

Request Parameters

Parameter	Type	Required	Description
Username	string	Yes	Your account username
Password	string	Yes	Your account password

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": "2025-11-28T23:59:59Z",
  "eventId": "evt_12345"
}

Response Fields

Field	Type	Description
token	string	The Bearer token to use for subsequent requests
expires	datetime	Token expiration timestamp (UTC)
eventId	string	Unique event identifier for this token creation

Using the Token

Once you have obtained a token, include it in the Authorization header for all subsequent API requests:

curl -X GET "https://api.example.com/api/v1/transcripts" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Expiration

Tokens have a limited lifespan (typically 24 hours). When a token expires:

1. You will receive a 401 Unauthorized error
2. You need to request a new token using the credentials endpoint
3. Update your application to use the new token

Best Practices

1. Store Tokens Securely

• Never hardcode credentials or tokens in source code
• Use environment variables or secure configuration management
• Store tokens in secure storage (e.g., secure vaults, encrypted databases)

2. Token Refresh Strategy

Implement a token refresh mechanism in your application:

// Pseudo-code example
async function getValidToken() {
  if (currentToken && !isExpired(currentToken)) {
    return currentToken;
  }
  
  const newToken = await fetchNewToken(username, password);
  return newToken;
}

3. Error Handling

Always handle authentication errors gracefully:

# Invalid credentials
curl -X POST "https://api.example.com/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"Username":"invalid","Password":"wrong"}'

# Response: 401 Unauthorized

4. Token Security

• Never log or expose tokens in logs
• Use HTTPS for all requests
• Regenerate tokens regularly
• Invalidate tokens when changing passwords

Code Examples

cURL

# Get token
TOKEN=$(curl -s -X POST "https://api.example.com/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"Username":"user","Password":"pass"}' \
  | jq -r '.token')

# Use token
curl -X GET "https://api.example.com/api/v1/transcripts" \
  -H "Authorization: Bearer $TOKEN"

C#

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

var client = new HttpClient();

// Get token
var payload = JsonSerializer.Serialize(new 
{ 
  Username = "your_username", 
  Password = "your_password" 
});
var content = new StringContent(payload, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.example.com/api/v1/auth/token", content);
response.EnsureSuccessStatusCode();

var responseBody = await response.Content.ReadAsStringAsync();
var tokenResponse = JsonSerializer.Deserialize<JsonElement>(responseBody);
var token = tokenResponse.GetProperty("token").GetString();

// Use token in subsequent requests
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
var data = await client.GetStringAsync("https://api.example.com/api/v1/transcripts");

Python

import requests
import json

# Get token
auth_url = "https://api.example.com/api/v1/auth/token"
credentials = {
    "Username": "your_username",
    "Password": "your_password"
}

response = requests.post(auth_url, json=credentials)
token_response = response.json()
token = token_response['token']

# Use token in subsequent requests
headers = {
    "Authorization": f"Bearer {token}"
}

transcripts = requests.get(
    "https://api.example.com/api/v1/transcripts",
    headers=headers
)
print(transcripts.json())

JavaScript

// Get token
async function getAuthToken(username, password) {
  const response = await fetch('https://api.example.com/api/v1/auth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ Username: username, Password: password })
  });
  
  const data = await response.json();
  return data.token;
}

// Use token
async function getTranscripts(token) {
  const response = await fetch('https://api.example.com/api/v1/transcripts', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  
  return response.json();
}

// Usage
const token = await getAuthToken('username', 'password');
const transcripts = await getTranscripts(token);

Troubleshooting

401 Unauthorized

• Verify your credentials are correct
• Check if your token has expired
• Ensure the Authorization header format is correct: Bearer <token>
• Check if the Bearer token is being sent correctly

403 Forbidden

• You have provided a valid token, but don't have permission to access this resource
• Contact support to verify your account permissions

Token Expiration

• Implement token refresh logic in your application
• Store token expiration time from the response
• Refresh tokens before they expire

Security Considerations

• HTTPS Only: Always use HTTPS for all API requests
• Rate Limiting: Be aware of rate limits on the token endpoint
• Credential Rotation: Regularly update your credentials
• Audit Logging: Monitor and log authentication attempts
• Secure Storage: Never commit credentials to version control