APIs Sam API Access update

This page explains how to update Skylark accesses, both individually and in batches.
It focuses on behavior, rules, and constraints, rather than repeating the full OpenAPI specification.

An access update can be used to:

  • Rotate credentials (password reset)
  • Change lifecycle state (ACTIVE / SUSPENDED / TERMINATED)
  • Terminate multiple accesses in bulk (PPU only)

When to use single vs batch update

Use single access update when:

  • You need to update one access at a time
  • You want an immediate, synchronous response
  • You are rotating credentials or changing status for a specific access

Use batch update when:

  • You need to update or terminate multiple accesses at once
  • You are performing operational changes in bulk
  • You are working with Pay-Per-Use (PPU) accesses

Batch update operations are processed asynchronously and require task polling.

Single access update

Endpoint

PATCH /{tenantName}/access/{id}

Single access update is a synchronous operation.
If the request is valid, the API immediately returns the updated access.

Content-Type requirement

Content-Type: application/merge-patch+json

Requests with a different content type are rejected.

Supported update fields

The following fields are supported:

  • password
    Rotates the access password.
  • status
    Updates the lifecycle state of the access.

❌ The following fields are not supported:

  • contractId
  • username
  • productOfferingId
  • deviceName

Status semantics

Available statuses for the update command:

Status valueMeaning
ACTIVEAccess is enabled and usable
SUSPENDEDAccess is temporarily disabled
TERMINATEDAccess is permanently terminated

Password rules

  • Password must be a UTF-8 string (maximum 72 bytes)
  • Passwords are returned only in update responses
  • Passwords are stored securely and cannot be retrieved later
  • To rotate credentials, a new password must be supplied

Request rules

  • At least one field must be present
  • Empty request bodies ({}) are rejected
  • null values are not allowed

Example: update password

{
  "password": "newSecurePass123"
}

Example: suspend access

{
  "status": "SUSPENDED"
}

Example: update password and status

{
  "password": "newSecurePass123",
  "status": "ACTIVE"
}

Response

The response contains an updated RealizingResource.

Batch access update

Endpoint

POST /{tenantName}/access/batchUpdate

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

Supported batch operations

Batch update supports two mutually exclusive operation types.

1. Batch update

Use this operation to:

  • Rotate passwords
  • Change access status

⚠️ Only Pay-Per-Use (PPU) accesses are supported.

Example

{
  "operationType": "update",
  "accessesIdList": [
    "access-001",
    "access-002"
  ],
  "operationBody": {
    "status": "SUSPENDED"
  }
}

Notes

  • All accesses must belong to the same tenant
  • Partial failures are possible
  • Each access is validated independently

2. Batch terminate

Use this operation to:

  • Terminate multiple accesses permanently

⚠️ Only Pay-Per-Use (PPU) accesses are supported.

Termination:

  • Sets the expiration date to the end of the current billing period
  • Does not require additional payload data

Example

{
  "operationType": "terminate",
  "accessesIdList": [
    "access-003",
    "access-004"
  ],
  "operationBody": {}
}

operationBody must be an empty object for termination.

Task-based processing for batch updates

Batch update operations return a Task object:

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

Task lifecycle

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

Polling for results

Clients must poll:

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

When the task reaches DONE, the response includes:

  • Successfully updated accesses
  • Error details for failed items (if any)

Common mistakes to avoid

  • Sending an empty PATCH body
  • Expecting immediate results from batch updates
  • Attempting batch updates on non-PPU accesses

Next steps

Read and filter accesses

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

API reference

View the full Skylark Access Management OpenAPI specification.