APIs Sam API API reference

This page provides the canonical API reference for the Skylark Access Management (SAM) API.

All functional behavior described in the previous guides (creation, read, update, and asynchronous operations) is formally defined in the OpenAPI specification linked below.

The OpenAPI document is the single source of truth for:

  • Available endpoints
  • Request and response schemas
  • Validation rules
  • Error models
  • Authentication requirements

OpenAPI specification

The Skylark Access Management API is documented using OpenAPI 3.0.

You can use the specification to:

  • Explore endpoints interactively via Swagger UI
  • Generate client SDKs
  • Validate requests and responses
  • Understand error handling and edge cases

Specification file

  • Filename: sam-v1.0.0.yml
  • Format: OpenAPI 3.0
  • Scope: External (customer-facing) SAM endpoints only

Internal and non-public endpoints are intentionally excluded.

What the specification includes

The OpenAPI document fully describes:

  • Access operations

    • Single access creation
    • Batch access creation
    • Access retrieval (list, filter, get by ID)
    • Single and batch updates

  • Asynchronous processing

    • Task (job-*) lifecycle
    • Polling endpoints
    • Success, partial success, and failure states

  • Schemas

    • RealizingResource
    • Task
    • Batch request and response models
    • TMF-style Problem error objects

  • Validation rules

    • Required vs optional fields
    • Content-Type enforcement
    • Mutual exclusivity in batch requests
    • Lifecycle state constraints

  • Security

    • OAuth 2.0 client credentials flow
    • Operation-level scopes

Using the specification

You can use the OpenAPI specification in multiple ways:

  • Swagger UI

    • Browse endpoints
    • Try requests interactively
    • Inspect schemas and examples

  • Client generation

    • Generate SDKs using tools like OpenAPI Generator
    • Ensure strong typing and request validation

  • Contract validation

    • Validate payloads before sending requests
    • Align client behavior with server-side rules

Versioning and compatibility

  • The API follows contract-first principles
  • Changes to the specification reflect actual runtime behavior
  • Schema strictness is intentional and aligned with backend validation

When upgrading between versions:

  • Review schema changes carefully
  • Pay special attention to stricter enums and required fields
  • Refer to release notes if available

For conceptual explanations and usage guidance, refer back to:

  • Get started – High-level concepts and authentication
  • Access creation – Single and batch provisioning
  • Access read – Listing, filtering, and retrieval
  • Access update – Credential and lifecycle updates
  • Asynchronous operations – Task lifecycle and polling

These pages explain how to use the API, while the OpenAPI specification defines exactly how the API behaves.

Final note

If there is any discrepancy between narrative documentation and the OpenAPI specification,
the OpenAPI specification always takes precedence.

It represents the authoritative contract exposed to external consumers.