twinsphere Management API

The Management API enables secure automation of core RBAC, identity, tenant, user, and service account operations within an organization. This API is designed for two audiences:

• twinsphere administrators who use the in-browser UI to manage their organization
• engineering teams integrating twinsphere capabilities into internal platforms, provisioning workflows or infrastructure automation pipelines

Getting Started

Important endpoints:

• the API itself is available under: https://manage.twinsphere.io/api ⧉
• OpenAPI specification: https://manage.twinsphere.io/openapi/v1.json ⧉
• Swagger UI (browser-based): https://manage.twinsphere.io/swagger/index.html ⧉

For each API request you need:

• the API version (currently only v1: https://manage.twinsphere.io/api/v1 ⧉)
• an authenticated principal (user or service account)
• your organization ID

Initially, each organization has a single user with rights to invite other users and create service accounts.

Self check via /me endpoint

To check your currently assigned organizations, tenants and roles simply use the /me endpoint.

Features

The Management API currently allows:

• user management within an organization
• service account management (including secrets)
• organizing users and service accounts via user groups
• RBAC at organization and cloud (per cloud tenant) levels
  • on users and service accounts
  • on user groups
• audit trail of all management operations

Authentication

1. Open the Management API Swagger UI in your browser: https://manage.twinsphere.io/swagger/index.html ⧉
2. Use the Authorize (green) button on the right
3. Choose one of the available authentication methods:
   • Bearer: paste an existing bearer token (useful when testing service accounts)
   • OAuth2: authenticate using your twinsphere ID account

You can also call the API with any HTTP client (e.g., curl). Using the Swagger UI is optional.

Inviting users

You can invite any user to your organization using their twinsphere ID. If the user does not yet have one, they can register themselves.

To invite a user, use: POST /api/v{version}/organizations/{organizationId}/users/invite

Audit trail

The audit trail provides a chronological record of all management operations performed in your organization. It is accessible only to organization owners.

GET /api/v{version}/organizations/{organizationId}/audit-trail

Query parameters

Parameter	Type	Required	Description
resourceType	string	No	Filter by resource type (see table below)
principalId	string	No	Filter by who performed the action
from	DateTime	No	Start of time range (ISO 8601, inclusive)
to	DateTime	No	End of time range (ISO 8601, exclusive)
pageSize	int	No	Items per page (default: 50, max: 200)
cursor	string	No	Pagination cursor from previous response

Results are sorted by timestamp descending (newest first).

Recorded operations

Resource type	Actions	Description
user	invite, remove	User invitations and removals
group	create, delete	User group lifecycle
group-membership	assign, remove	Adding or removing members from a group
org-role-assignment	assign, unassign	Organization-level role assignments
tenant-role-assignment	assign, unassign	Tenant-level role assignments
service-account	create, delete	Service account lifecycle
service-account-secret	create, delete	Service account secret lifecycle

Each audit entry includes the timestamp, the principal who performed the action, the affected resource, and optional contextual details (e.g. role name, tenant ID, target principal).

Role-based access control (RBAC)

For any organization member (user) or any service account you created, you can create role assignments to define their access. Roles can be assigned at:

• organization (global) level
• cloud level (per cloud tenant)

Organization-level roles implicitly grant access to all cloud tenants and should be limited to administrators or super-users.

List available roles:

• GET /api/v{version}/organizations/{organizationId}/roles
• GET /api/v{version}/organizations/{organizationId}/cloud/roles

Assign the organization-owner role:

• POST /api/v{version}/organizations/{organizationId}/role-assignments

Assign a role for a single cloud tenant (e.g., read-only AAS data):

• POST /api/v{version}/organizations/{organizationId}/cloud/{tenantId}/role-assignments

Service accounts

Service accounts provide headless (machine-to-machine) access.

Create a service account: POST /api/v{version}/organizations/{organizationId}/service-accounts

Add a secret to a service account: POST /api/v{version}/organizations/{organizationId}/service-accounts/{serviceAccountId}/secrets

User groups

User groups provide an easier way to assign roles to multiple users or service accounts at once.

Create a user group: POST /api/v{version}/organizations/{organizationId}/user-groups

Add members to a user group: POST /api/v{version}/organizations/{organizationId}/user-groups/{groupId}/members