APIs Sam API Get started

Welcome to the Skylark Access Management Get Started guide!
This chapter provides a high-level introduction to the Skylark Access Management API, helping you understand how to create, read, and update access credentials for Skylark services.

An access represents a set of credentials and metadata associated with a customer contract and a product offering. These credentials are used by devices or applications to authenticate against Skylark services.

https://myiot-d.com/docs/images/sam/sam-architecture.png does not exist

Key concepts

Before working with the API, it is important to understand the following concepts:

Access

An access contains:

  • Authentication credentials (e.g. username and password)
  • A reference to a customer contract
  • A product offering (such as a Skylark service plan)
  • Lifecycle state information

Accesses are exposed through the API as TMF-style RealizingResource objects.

Synchronous vs asynchronous operations

The API supports both synchronous and asynchronous workflows:

  • Synchronous operations

    • Single access creation
    • Access read operations
    • Access updates

  • Asynchronous operations

    • Batch access creation
    • Batch updates

Asynchronous operations return a Task object that must be polled until completion.

Task-based processing

For batch operations, the API responds with a task reference (job-* identifier).
Clients are expected to poll the task endpoint to retrieve the final result:

  • ACKNOWLEDGED / IN_PROGRESS – processing ongoing
  • DONE – operation completed successfully
  • REJECTED / FAILED – operation did not complete successfully

Authentication

The Skylark Access Management API uses OAuth 2.0 client credentials authentication.

  • Clients must obtain an access token from the IoT Hub authorization service
  • Required scopes are defined per operation and documented in the API specification
  • The access token must be provided using the Authorization: Bearer <token> header

What happens automatically

To simplify client integrations, the system can automatically generate certain values when they are not provided:

  • Password – generated securely if omitted during creation
  • Username – generated based on tenant and access context when not explicitly supplied
  • Lifecycle metadata – activation and expiration timestamps are derived from the contract

These behaviors are explained in detail in the access creation sections.

Where to go next

Use the following guides to start working with the API:

Create accesses (single and batch)

Learn how to create single or multiple accesses and understand which fields are required or auto-generated by the system.

Read and filter accesses

Learn how to retrieve accesses, apply filters, and paginate through large result sets.

Update accesses

Learn how to update access credentials and lifecycle state, including batch update operations.

API reference

For full request and response details, refer to the Skylark Access Management OpenAPI specification, which documents all endpoints, schemas, and examples in detail.