APIs Sam API Access read

This page explains how to retrieve Skylark accesses, either as a list or individually. It focuses on query behavior, filtering rules, and pagination, not on repeating the full OpenAPI specification.

An access represents a set of credentials and metadata linked to a customer contract and a product offering. Accesses are returned as TMF-style RealizingResource objects.

Lifecycle

The API exposes status-based lifecycle management via the status field:

Status valueMeaning
PENDING_ACTIVEAccess is going to be activated with the first connection to it (Prepaid only)
ACTIVEAccess is enabled and usable
SUSPENDEDAccess is temporarily disabled
PENDING_TERMINATEAccess is going to be terminated by the end of the month
TERMINATEDAccess is permanently terminated

List accesses

Endpoint

GET /{tenantName}/access

This endpoint returns a paginated list of accesses for the given tenant.

Filtering accesses

You can filter results using query parameters. Only supported filters are applied; unsupported parameters are ignored.
Combine conditions with ‘&’ for AND and ‘;’ for OR.

Supported filters

  • contractId
    Returns accesses linked to a specific customer contract. Supported operators: ["="].

  • productOfferingId
    Filters by product offering identifier (the canonical identifier coming from IoT Store). Supported operators: ["="].

  • createdBy
    Filters accesses by the originator job’s ID. Supported operators: ["="].

  • name
    Access’ name. Supported operators: ["="].

  • username
    Access’ username. Supported operators: ["="].

  • createdAt
    Filters accesses by creation timestamp. Supported operators: [">", “>=”, “<”, “<=”, “=”]. This field is filter-only and is not returned in responses.

  • startDateTime
    Access’ start of the active time period. Supported operators: [">", “>=”, “<”, “<=”, “=”].

  • endDateTime
    Access’ end of the active time period. Supported operators: [">", “>=”, “<”, “<=”, “=”].

Example

GET /eos/access?filter=contractId=1200035908&productOfferingId=PRP_SKYRTK_EU_12

Pagination

List results are always paginated.

Pagination is controlled using the standard RFC 5988 Link header. Total count of accesses available displayed using X-Total-Count header. Both headers are influeced by the filter query (if used), so it only represents total count and pages structure for accesses that are filtered in. The response body contains only the current page of results.

Example Link header:

Link: <https://api.example.com/eos/access?pageNumber=20&pageSize=10>; rel="last", <https://api.example.com/eos/access?pageNumber=1&pageSize=10>; rel="first", <https://api.example.com/eos/access?pageNumber=17&pageSize=10>; rel="next"

Example X-Total-Count header:

X-Total-Count: 130

Important notes

  • Clients must follow the Link header to retrieve additional pages
  • Pagination behavior is consistent across all list endpoints

List response

The response body contains an array of RealizingResource objects.

Retrieve a single access

Endpoint

GET /{tenantName}/access/{accessId}

This endpoint returns a single access by its identifier.

Example

GET /eos/access/eos_1954829761

Behavior

  • Returns 200 OK with the access if found
  • Returns 404 Not Found if the access does not exist or is not visible to the tenant

Headers

All read operations require:

  • Authorization: Bearer <token>

Optional:

  • Correlation ID header (if supported by the client environment)

Common mistakes to avoid

  • Using unsupported filter parameters
  • Assuming list endpoints return all results in a single response

Next steps

Update accesses

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