APIs Sam API Access creation

This page explains how to create Skylark accesses, both individually and in batches.
It focuses on behavior and rules, 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. These credentials are used by devices or applications to authenticate against Skylark services.

When to use single vs batch creation

Use single access creation when:

  • You need to create one access at a time
  • You want an immediate, synchronous response
  • You are provisioning accesses on-demand

Use batch access creation when:

  • You need to create multiple accesses at once
  • You want the platform to generate many accesses automatically
  • You are onboarding devices in bulk

Batch operations are processed asynchronously and require task polling.

Single access creation

Endpoint

POST /{tenantName}/access

Single access creation is a synchronous operation.
If the request is valid, the API immediately returns the created access.

Required fields

  • contractId
    Identifies the customer contract under which the access is created.

Optional fields

  • username
    If not provided, the system generates a unique username.
  • password
    If not provided, the system generates a secure password.
  • deviceName
    Optional logical name for the access.

Automatic behavior

If omitted, the system automatically:

  • Generates a username
  • Generates a password
  • Derives lifecycle metadata (activation and expiration) from the contract

Example (single access)

{
  "contractId": "contract-001",
  "deviceName": "device-alpha"
}

Response

The response contains a RealizingResource object with:

  • Generated credentials
  • Product offering information
  • Lifecycle validity period

Batch access creation

Endpoint

POST /{tenantName}/access/batch

Batch access creation is an asynchronous operation.
The API responds immediately with a Task reference, while processing continues in the background.

Two batch creation modes

You must choose exactly one of the following modes.

1. Create a fixed number of accesses

Use this mode when:

  • You want the system to generate multiple accesses automatically
  • You do not care about individual usernames or device names

Example

{
  "numberOfAccesses": 5,
  "contractId": "contract-001"
}

The system generates:

  • Usernames
  • Passwords
  • Device names (if applicable)

2. Create explicit accesses

Use this mode when:

  • You want control over individual access attributes
  • You need to specify usernames or device names

Example

{
  "accesses": [
    { "deviceName": "device-1" },
    { "deviceName": "device-2" }
  ],
  "contractId": "contract-001"
}

Passwords and usernames are still generated automatically if omitted.

Task-based processing for batch operations

Batch creation does not return accesses directly.

Instead, the API responds with a Task object:

{
  "id": "job-123456",
  "state": "ACKNOWLEDGED"
}

Task lifecycle

  • ACKNOWLEDGED / IN_PROGRESS – processing ongoing
  • DONE – batch completed successfully
  • REJECTED / FAILED – batch failed

Polling for results

Clients must poll:

GET /{tenantName}/access/batch/{taskId}

When the task reaches DONE, the response includes:

  • Successfully created accesses
  • Errors for failed items (if any)

Password and credential handling

  • Passwords are returned in the creation responses

Common mistakes to avoid

  • Sending both numberOfAccesses and accesses in the same batch request
  • Expecting immediate results from batch creation
  • Assuming passwords can be retrieved later
  • Using batch creation for single-access use cases

Next steps

Read and filter accesses

Learn how to retrieve accesses, apply filters, and paginate through results.

Update accesses

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