Skip to main content

​
Authentication

All requests to the Sterndesk API require authentication using an API key. This page explains how to obtain credentials and authenticate your requests.

​
Obtaining an API Key

API keys are currently issued directly by our team. To request access:

Request API Access

Contact us to request your API key
 Once approved, you’ll receive your API key via email. Store this key securely.

​
Creating Additional API Keys

Within an organization, you can create additional API keys programmatically using the API. This allows you to issue separate keys for different team members, services, or environments. Use the POST /api-keys endpoint to create new keys: 
curl -X POST "https://api.sterndesk.com/r/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_...", "description": "Production service key"}'
See Organizations & Projects to learn more about managing access within your organization.

​
Using Your API Key

Authenticate all API requests by including your key in the Authorization header using the Bearer scheme: 
Authorization: Bearer YOUR_API_KEY

​
Example Request

curl -X GET "https://api.sterndesk.com/r/who-am-i?echo=test" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Testing Your Authentication

Use the /who-am-i endpoint to verify that your API key is working correctly. This endpoint returns information about the authenticated identity. 
curl -X GET "https://api.sterndesk.com/r/who-am-i?echo=hello" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Successful Response

A successful authentication returns your identity information: 
{
  "webUserAuthIdentity": "your-auth-identity",
  "numOrganizations": 1,
  "numUsers": 1,
  "mustInitializeUser": false,
  "currentUserId": "usr_abc123..."
}

​
Error Response

If your API key is invalid or missing, you’ll receive an authentication error: 
{
  "code": "permission_denied",
  "message": "invalid or missing API key"
}

​
Security Best Practices

Never expose your API key in client-side code, public repositories, or logs.
  • Use environment variables to store your API key
  • Rotate keys periodically if you suspect they may have been compromised
  • Use separate keys for development and production environments

​
Next Steps

Quickstart

Make your first extraction request

Extraction Schemas

Define what data to extract from your documents