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

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"

import requests

response = requests.get(
    "https://api.sterndesk.com/r/who-am-i",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"echo": "hello"}
)
print(response.json())

const response = await fetch(
  "https://api.sterndesk.com/r/who-am-i?echo=hello",
  {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  }
);
const data = await response.json();
console.log(data);

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

Get Started

Concepts

Guides

Authentication

Authentication

Obtaining an API Key

Request API Access

Creating Additional API Keys

Using Your API Key

Example Request

Testing Your Authentication

Successful Response

Error Response

Security Best Practices

Next Steps

Quickstart

Extraction Schemas

​Authentication

​Obtaining an API Key

Request API Access

​Creating Additional API Keys

​Using Your API Key

​Example Request

​Testing Your Authentication

​Successful Response

​Error Response

​Security Best Practices

​Next Steps

Quickstart

Extraction Schemas

Authentication

Obtaining an API Key

Creating Additional API Keys

Using Your API Key

Example Request

Testing Your Authentication

Successful Response

Error Response

Security Best Practices

Next Steps