Skip to main content

​
Overview

The Notra API uses Unkey for authentication and authorization. All requests to /v1/* endpoints require a valid API key sent via the Authorization header using Bearer authentication.

​
Authentication Method

Notra uses Bearer token authentication with the following format: 
Authorization: Bearer YOUR_API_KEY
Never expose your API keys in client-side code, public repositories, or any publicly accessible locations. Always keep your keys secure and use environment variables.

​
Generating an API Key

To generate an API key for your organization:
  1. Log in to your Notra dashboard
  2. Navigate to Settings > API Keys
  3. Click Create New API Key
  4. Provide a descriptive name for the key
  5. Copy and securely store your API key
API keys are only displayed once during creation. If you lose your key, you’ll need to generate a new one.

​
Making Authenticated Requests

Include your API key in the Authorization header of every request: 
curl https://api.usenotra.com/v1/{organizationId}/posts \
  -H "Authorization: Bearer notra_xxxxxxxxxxxxxxxxxxxxxx"

​
Permissions

API keys are scoped with specific permissions. The Notra API currently requires the following permission:
​
api.read
string
required
Required for all read operations on content endpoints. This permission allows you to list and retrieve posts for your organization.
Keys without the necessary permissions will receive a 403 Forbidden response: 
{
  "error": "Forbidden"
}

​
Organization Scope

API keys are tied to a specific organization via the externalId identity field. When making requests:
  1. The {organizationId} in the URL path must match your key’s organization
  2. Attempts to access other organizations will result in a 403 Forbidden error
Each API key can only access content for its associated organization. This ensures data isolation and security.

​
Error Responses

The API returns specific error codes for authentication issues:

​
401 Unauthorized - Missing API Key

{
  "error": "Missing API key"
}
This occurs when the Authorization header is not provided.

​
401 Unauthorized - Invalid API Key

{
  "error": "INVALID_KEY"
}
The provided API key is invalid or has been revoked.

​
403 Forbidden - Insufficient Permissions

{
  "error": "Forbidden"
}
Your API key lacks the required permissions for this operation.

​
403 Forbidden - Organization Access Denied

{
  "error": "Forbidden: organization access denied"
}
You’re attempting to access an organization that your API key doesn’t have access to.

​
503 Service Unavailable

{
  "error": "Service unavailable"
}
The authentication service is temporarily unavailable. Please retry your request.

​
Best Practices

​
Store Keys Securely

Always use environment variables or secret management services:
.env
NOTRA_API_KEY=notra_xxxxxxxxxxxxxxxxxxxxxx

​
Rotate Keys Regularly

For enhanced security:
  1. Generate a new API key
  2. Update your applications to use the new key
  3. Delete the old key once migration is complete

​
Use Separate Keys for Different Environments

Create dedicated API keys for:
  • Development
  • Staging
  • Production
This allows you to revoke keys without affecting other environments.

​
Handle Authentication Errors Gracefully

Implement proper error handling in your application: 
try {
  const response = await fetch(url, { headers });
  
  if (response.status === 401) {
    // Handle invalid or missing API key
    console.error('Authentication failed');
  } else if (response.status === 403) {
    // Handle permission issues
    console.error('Access forbidden');
  }
  
  const data = await response.json();
} catch (error) {
  console.error('Request failed:', error);
}

​
Next Steps

Rate Limits

Learn about API rate limits and quotas

API Reference

Explore available endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us