Skip to main content

Authentication

SASHA Partner API implements OAuth 2.0 Client Credentials flow with short-lived Bearer tokens. The API provides both authentication and signature operations through a unified interface.

Authentication process

Authentication Architecture​

Partner API - A comprehensive service that handles both authentication and signature operations. The API lives at partner.api.sasha.eu and provides:

  • Authentication endpoint for obtaining access tokens
  • SASHA Signature embedding and lookup operations

This unified design provides several benefits:

  • Simplified integration: Single endpoint for all operations reduces configuration complexity
  • Token-based security: All operations use short-lived access tokens, reducing the attack surface
  • Consistent authorization: All endpoints follow the same authentication and authorization patterns

OAuth 2.0 Client Credentials Flow​

SASHA implements the OAuth 2.0 Client Credentials grant type, a standard authentication pattern designed specifically for server-to-server communication where no end user is involved.

Here's how it works in the SASHA context:

  1. Authentication Request: You send your Client ID and Client Secret to the Get Token REST API authentication endpoint using HTTP Basic Authentication (REST) or the AuthenticateWithClientCredential RPC (gRPC). These credentials prove your identity as a verified SASHA Partner.

  2. Token Issuance: The PartnerAPI validates your credentials and returns an access token. This token is a temporary credential that grants you access to the API.

  3. API Access: You include the access token in the Authorization: Bearer <token> header when calling Partner API endpoints. The API validates the token and processes your request.

  4. Token Expiration: After a predetermined period, the token expires and can no longer be used. You must request a new token to continue making API calls.

This flow follows the OAuth 2.0 specification, which means it's well-documented, widely understood, and supported by most HTTP client libraries and frameworks.

Security Model​

Trust Boundaries​

Understanding SASHA's trust boundaries helps you design secure integrations:

Long-lived Credentials (Client ID + Client Secret)

  • Represents your partner identity
  • Should be treated like a password
  • Only transmitted to PartnerAPI authentication endpoint over HTTPS
  • Should never be logged, committed to version control, or exposed in client-side code
  • Acts as the root of trust for your integration

Short-lived Access Tokens

  • Temporary credentials with limited validity
  • Can be cached and reused during their lifetime
  • Automatically expire, limiting the damage if compromised
  • Can be logged for debugging (though not recommended in production)
  • Lower security risk than long-lived credentials

Why Short-lived Tokens?​

SASHA access tokens are intentionally short-lived as a security measure. This design choice provides several benefits:

Reduced exposure window: If a token is compromised (through logging, network interception, or other means), it becomes useless after expiration. An attacker has only a limited time window to abuse it.

Forced rotation: Regular token renewal ensures that your integration regularly proves it still has valid credentials. This helps detect credential revocation or security issues quickly.

Containment strategy: In a security incident, short-lived tokens mean that simply waiting for expiration can be part of the remediation strategy, rather than requiring immediate token revocation.

The expires_in field in the authentication response tells you exactly how long the token remains valid, allowing you to plan your token renewal strategy accordingly.

Token Lifecycle Management​

Understanding Token States​

An access token moves through several states during its lifecycle:

Active: The token is valid and can be used to make API calls. This is the normal operational state.

Near-expiration: The token is still valid but approaching its expiration time. This is when proactive renewal should occur.

Expired: The token's validity period has ended. API calls with an expired token will receive a 401 Unauthorized response.

Renewed: You've obtained a new token before the old one expired. The old token may still be valid for a brief period.

Renewal Strategies​

There are two fundamental approaches to token renewal, each with different trade-offs:

Reactive Renewal​

Wait for the Partner API to reject your request with 401 Unauthorized, then request a new token and retry.

When to use: Low-traffic integrations or scenarios where brief interruptions are acceptable.

Implementation approach:

  • Make API calls with your current token
  • If you receive a 401 error, immediately request a new token from PartnerAPI
  • Retry the failed request with the new token
  • Continue with the new token

Trade-offs:

  • ✅ Simple implementation with minimal state tracking
  • ✅ No risk of premature renewal
  • ✅ Works well for sporadic API usage
  • ❌ Brief service interruption when token expires
  • ❌ Additional latency on the first request after expiration
  • ❌ Requires retry logic in your API client

Proactive Renewal​

Monitor token expiration time and request a new token before the current one expires.

When to use: High-traffic integrations or scenarios where uninterrupted service is critical.

Implementation approach:

  • Store the token along with its expiration time
  • Before each API call, check if the token is near expiration
  • If expiration is approaching (e.g., 80% of lifetime has passed), request a new token
  • Switch to the new token for subsequent requests

Trade-offs:

  • ✅ No service interruption
  • ✅ Predictable renewal behavior
  • ✅ Better user experience
  • ❌ More complex implementation
  • ❌ Requires tracking expiration time
  • ❌ May renew tokens that won't be used (in low-traffic scenarios)

Production-Grade Token Management​

For production systems, implement a robust token management strategy:

Track expiration accurately: When you receive a token, calculate the exact expiration timestamp (current_time + expires_in) and store it alongside the token. Don't rely on approximate timing.

Renew proactively with buffer: Don't wait until the last second. Request a new token when 70-80% of the token lifetime has passed. This gives you buffer time to handle network delays or PartnerAPI issues.

Handle concurrent requests: If multiple threads or processes might need tokens simultaneously, implement coordination to avoid requesting multiple tokens at once. Consider using a mutex or distributed lock.

Implement retry logic: Authentication requests can fail due to network issues or temporary service problems. Implement exponential backoff retry logic for token requests.

Cache tokens appropriately: Store tokens in a way that allows reuse across multiple API calls but doesn't compromise security. In-memory caching is usually sufficient; avoid writing tokens to disk unless properly encrypted.

Monitor renewal health: Track token renewal metrics (success rate, latency, failure reasons) to detect authentication issues before they impact your service.

Example Timeline​

Here's what a production-grade proactive renewal might look like:

T=0s      Obtain token (expires_in: 3600s)
T=0-2880s Use token for all API calls
T=2880s   Renewal threshold reached (80% of lifetime)
T=2880s   Request new token in background
T=2881s   New token obtained, switch to using it
T=3600s   Old token expires (but we're already using the new one)

Security Best Practices​

Credential Protection​

Your Client ID and Client Secret are the keys to your SASHA integration. Protect them as you would any password:

Never commit to version control: Use environment variables, secret management services (like AWS Secrets Manager, HashiCorp Vault), or configuration files excluded from version control.

Limit exposure: Only share credentials with team members who need them.

Rotate regularly: Periodically request new credentials from SASHA, especially if team members with access leave or if you suspect compromise.

Server-side only: Never include credentials in client-side code (web browsers, mobile apps). Always authenticate from your backend servers.

Token Handling​

While tokens are less sensitive than credentials, treat them with care:

Use HTTPS always: All communication with SASHA APIs must use HTTPS. Never send tokens over unencrypted HTTP.

Minimize logging: Avoid logging full tokens in production. If you must log for debugging, redact the token or use a truncated version.

Don't share across systems: Each system should obtain its own tokens. Don't copy tokens between systems.

Clear on logout/shutdown: When your application shuts down or a session ends, clear tokens from memory if possible.

Callback Authentication​

When you configure callbacks to receive job status notifications, SASHA needs to authenticate itself to your callback endpoint. This creates a reverse authentication flow with two layers of security:

Partner Authentication Token​

SASHA includes a unique authentication token in the Authorization: Bearer <token> header when calling your callbacks. Your callback endpoint should verify this token to ensure the request genuinely comes from SASHA and not an attacker attempting to forge job notifications.

Each Partner receives a unique Partner Authentication Token, separate from your Client ID and Client Secret.

Callback Payload Signature​

To protect the callback payload from tampering during transit, SASHA provides an HMAC-SHA256 signature of the request in the SASHA-Request-Signature header.

How it works:

  1. SASHA uses your Callback Secret (a separate credential from the Partner Authentication Token) as the HMAC key
  2. The signature is calculated over: request_method || request_url || request_id || request_payload
  3. The signature is sent in the SASHA-Request-Signature header
  4. Your callback endpoint recomputes the signature and compares it with the received value

Security credentials you receive:

  • Partner Authentication Token - For Bearer token validation (proves sender identity)
  • Callback Secret - For HMAC-SHA256 signature validation (proves payload integrity)

While signature validation is optional, SASHA strongly recommends implementing it to ensure the payload genuinely comes from SASHA and was not modified in transit.

Request Identification​

Each callback delivery includes a unique SASHA-Request-ID header that you can use for tracking, debugging, and ensuring idempotency. This header is also included in the signature calculation to prevent replay attacks.

Bidirectional Authentication​

This security model ensures both parties can verify each other's identity: you authenticate to SASHA to make API calls, and SASHA authenticates to you when delivering callback notifications.