​
API Authentication

Welcome to the Altostrat SDX API documentation. This guide explains how to securely authenticate your requests depending on how you intend to interact with the platform.

API Base URL: https://api.altostrat.io

​
Authentication Methods Overview

Altostrat SDX utilizes distinct authentication methods tailored to different use cases:

  1. API Keys (Developer API):
  • Use Case: For external developers, scripts, or services integrating with Altostrat SDX programmatically.
  • Mechanism: Long-lived, team-specific API Keys used directly as Bearer tokens in the Authorization header.
  1. OAuth 2.0 (Web Application / SPA):
  • Use Case: Used by the official Altostrat SDX web application and potentially other first-party or trusted client applications authenticating as a user.
  • Mechanism: Standard OAuth 2.0 flows (Authorization Code or Implicit Grant) result in short-lived JWT Bearer tokens managed by the client application.
  1. Internal M2M Tokens:
  • Use Case: Communication between Altostrat’s internal backend microservices.
  • Mechanism: Service-specific, private Bearer tokens. Not available or documented for external use.

​
Developer API Authentication (Using API Keys)

To interact with the main Altostrat SDX API endpoints programmatically (e.g., managing teams, users, billing outside the official web UI), you need an API Key.

​
Obtaining an API Key

  • API Keys are generated within the Altostrat SDX web application.
  • Navigate to your Team Settings > API Credentials section. (Note: Exact UI path may vary).
  • You can create multiple keys, typically one per integration or application, giving each a descriptive name.
  • Each API Key is scoped to the specific Team it was created under. It can only access resources associated with that team.

​
API Key Format

An API Key has the following structure: {tokenId}:{teamId}:{secret}

  • tokenId: The unique UUID of the API token record.
  • teamId: The UUID of the team the token belongs to.
  • secret: A randomly generated secret string (62 characters).

Important: The {secret} part is only shown once upon creation. Store it securely.

​
Using the API Key

Include your full API Key in the Authorization header of your API requests using the Bearer scheme:

GET /teams HTTP/1.1
Host: api.altostrat.io
Authorization: Bearer 9c16437d-aaaa-bbbb-cccc-adfbfc156d0c:9b52d930-dddd-eeee-ffff-4c12dff85544:Kq5z...rA9p
Accept: application/json
Content-Type: application/json

(Replace the example key with your actual API Key)

​
Security & Rate Limiting

  • Treat your API Keys like passwords. Do not expose them in client-side code or public repositories.
  • Generate separate keys for different applications and revoke any compromised keys immediately via the web UI.
  • API requests using these keys are rate-limited to 60 requests per minute per key. Exceeding this limit will result in 429 Too Many Requests errors.

​
Web Application / SPA Authentication (OAuth 2.0)

The official Altostrat SDX web application (and potentially other trusted clients) uses OAuth 2.0 to authenticate users.

  • Flow: Users log in via the web interface (using username/password or an external Identity Provider like Google, Microsoft, GitHub). The application then handles an OAuth 2.0 flow (likely Authorization Code grant) to obtain a JWT (JSON Web Token).
  • Usage: This JWT is automatically included as a Bearer token in the Authorization header for subsequent API calls made by the web application itself.
  • End-User Impact: As an end-user using the web application, you don’t typically need to manage these JWTs directly; the application handles their lifecycle (obtaining, refreshing, using).
  • Developer Impact: If you are building a client application that needs to act on behalf of an Altostrat SDX user, you would implement a standard OAuth 2.0 client flow using the endpoints defined in our OpenID Connect Discovery Document.

​
Internal Machine-to-Machine APIs

These endpoints are used exclusively for communication between Altostrat SDX’s internal services (e.g., syncing site counts, triggering billing events).

  • They use separate, internal authentication mechanisms (e.g., M2mAuth, SiteInternalAuth Bearer tokens).
  • These APIs and their authentication details are not publicly exposed or documented for external use.

​
Summary: Choosing the Right Method

  • Integrating your service/script with Altostrat SDX? Use the Developer API Authentication with an API Key generated for your Team.
  • Using the official Altostrat SDX Web Application? Authentication is handled automatically via OAuth 2.0 / JWT.
  • Building a client that logs users into Altostrat SDX? Implement an OAuth 2.0 client flow.
  • Working on Altostrat’s internal infrastructure? Use the designated Internal M2M Authentication (details managed internally).

Next Steps: