Authorization

All API requests require authentication using JWT tokens signed with RSA keys. You’ll generate these tokens using a private RSA key obtained from your project, then include them in the Authorization header as a Bearer token.

Overview

The authorization flow involves:

  1. Generating an RSA key pair for your project
  2. Creating a JWT token with your user ID (subject) and required claims
  3. Including the JWT as a Bearer token in API requests
  4. The API validates the token using your project’s public key

Authentication Header

Include your JWT token in all API requests:

Authorization: Bearer YOUR_JWT_TOKEN

JWT Structure

All JWTs must use RS256 algorithm and include specific claims for proper authentication and authorization.

JWT Generation

Required Claims Structure

const jwt = require('jsonwebtoken');
 
// JWT Payload
const payload = {
  sub: 'user-12345',           // Subject: unique user identifier
  iss: 'project-abc123',       // Issuer: your project ID
  roles: ['private'],          // Roles: permissions array
  iat: Math.floor(Date.now() / 1000)  // Issued at time
};
 
// JWT Options
const options = {
  algorithm: 'RS256',
  keyid: 'key-456',           // Key ID from your project
  expiresIn: '1h'             // Token expiration
};
 
// Generate JWT
const token = jwt.sign(payload, privateKey, options);

Required Claims

ClaimTypeRequiredDescription
substringYesSubject: unique user identifier that scopes access to resources
issstringYesIssuer: your project ID (must match URL parameter)
rolesstring[]YesArray of roles, typically ['private'] for API access
iatnumberYesIssued at time (Unix timestamp)
expnumberYesExpiration time (Unix timestamp)

Header Requirements

HeaderTypeRequiredDescription
algstringYesMust be RS256
kidstringYesKey ID corresponding to your project’s RSA key

Project-Level Security

The API uses project-scoped authentication where:

  • JWT iss (issuer) must match the projectId in the URL path
  • JWT sub (subject) scopes access to user-specific resources
  • Only resources belonging to the authenticated subject are accessible

URL Structure

All API endpoints follow this pattern:

/projects/{projectId}/resource

The projectId must match the iss claim in your JWT token.

Validation & Error Handling

Validation Process

  1. Token Structure: JWT must be properly formatted with valid RS256 signature
  2. Project Matching: JWT iss must equal URL projectId parameter
  3. Subject Validation: For POST requests, entityId in body must match JWT sub
  4. Role Authorization: User must have required role (typically private)
  5. Key Verification: Token must be signed with valid project key

Common Errors

{
  "error": {
    "status": 401,
    "type": "unauthorized",
    "title": "Unauthorized", 
    "message": "Missing or invalid API key was provided."
  }
}

Security Best Practices

  1. Keep private keys secure - Never expose RSA private keys in client-side code
  2. Use appropriate expiration times - Shorter tokens (15-60min) for sensitive operations
  3. Rotate keys regularly - Implement key rotation for long-lived applications
  4. Validate on every request - API validates all tokens server-side
  5. Handle errors gracefully - Implement proper error handling and token refresh
  6. Use HTTPS only - All API communication must use TLS encryption