Skip to main content

Build integrations · Partner

SAPP read and metadata API

Read tenants, users, and memberships, then patch integration metadata without overwriting core ONE fields.

SAPP, the Skyfallen Account Provisioning Protocol, is the provisioning API for lifecycle systems that need a reliable view of ONE users, tenants, memberships, permissions, and integration metadata.

HTTP requestUse API key headers for SAPP and tenant signup calls, especially when the endpoint is a GET request.
PATCH /api/user/018fd4c0-e2da-7c7d-8b8e-0f033193b383 HTTP/1.1
Host: idms.skyfallen.one
Accept: application/json
Content-Type: application/json
X-Skyfallen-Client-Id: 9f2f0d28-8d32-4c6d-a4af-0b3a82c102f4
X-Skyfallen-Client-Secret: sapp_client_secret

{
  "metadata": {
    "hris_id": "HR-100044",
    "division": "Design",
    "temporary_import_id": null
  }
}

Authentication

Send API key credentials in headers:

For compatibility with older tenant signup clients, client_id and client_secret are also accepted as request inputs. Headers are preferred because several SAPP endpoints are GET requests.

HTTP requestUse API key headers for SAPP and tenant signup calls, especially when the endpoint is a GET request.
X-Skyfallen-Client-Id: {client_id}
X-Skyfallen-Client-Secret: {client_secret}
Accept: application/json
Content-Type: application/json
Method Path Purpose
GET /api/tenants Return every tenant visible to the API key.
GET /api/tenant/{tenant} Return one tenant.
PATCH /api/tenant/{tenant} Merge tenant metadata.
GET /api/users Return every user, including memberships.
GET /api/user/{user} Return one user, including memberships.
PATCH /api/user/{user} Merge user metadata.
GET /api/tenant/{tenant}/members Return memberships for one tenant, including user records and permissions.

Reading tenants

HTTP requestUse API key headers for SAPP and tenant signup calls, especially when the endpoint is a GET request.
GET /api/tenant/018fd4c2-57de-7bc4-8e53-4e5758c0f624 HTTP/1.1
Host: idms.skyfallen.one
Accept: application/json
X-Skyfallen-Client-Id: 9f2f0d28-8d32-4c6d-a4af-0b3a82c102f4
X-Skyfallen-Client-Secret: sapp_client_secret

A tenant response contains identity, billing, verification, branding, workforce, legacy SAML migration, and metadata fields.

Important tenant fields include:

Field Meaning
id Tenant identifier.
status not_verified, not_allowed, active, or disabled.
type direct, commercial, or enterprise.
region Skyfallen service region, for example INTL, TR, or UK.
secr Skyfallen Enterprise Customer Reference, when present.
subdomain Workforce vanity subdomain, when configured.
workforce_identity Whether workforce portal mode is enabled.
metadata Integration-owned tenant metadata.

Reading users

HTTP requestUse API key headers for SAPP and tenant signup calls, especially when the endpoint is a GET request.
GET /api/users HTTP/1.1
Host: idms.skyfallen.one
Accept: application/json
X-Skyfallen-Client-Id: 9f2f0d28-8d32-4c6d-a4af-0b3a82c102f4
X-Skyfallen-Client-Secret: sapp_client_secret

User responses include account profile fields and memberships. Hidden storage fields such as password hashes, remember tokens, verification codes, phone verification codes, and Persona references are not exposed.

Important user fields include:

Field Meaning
id User identifier.
status email_not_verified, no_tenant, active, or disabled.
email Primary email address.
secondary_emails Secondary addresses linked to the account.
phone_verified_at Phone verification timestamp, when present.
password_set Whether the user has set a password.
metadata Integration-owned user metadata.
memberships Tenant memberships included in user reads.

Reading memberships

HTTP requestUse API key headers for SAPP and tenant signup calls, especially when the endpoint is a GET request.
GET /api/tenant/018fd4c2-57de-7bc4-8e53-4e5758c0f624/members HTTP/1.1
Host: idms.skyfallen.one
Accept: application/json
X-Skyfallen-Client-Id: 9f2f0d28-8d32-4c6d-a4af-0b3a82c102f4
X-Skyfallen-Client-Secret: sapp_client_secret

Memberships connect users to tenants and carry a role identifier plus permissions.

Field Meaning
id Membership identifier.
tenant_id Tenant identifier.
user_id User identifier.
role_id Assigned tenant role UUID.
role Compact role object with id and name.
permissions Permission records. Each entry includes locked when the grant comes from the assigned role. * grants all permissions.
user Full user object on tenant member reads.
tenant Compact tenant object on user reads.

Metadata patches

PATCH endpoints update metadata only. They do not edit core ONE profile, tenant, role, or permission fields.

Metadata must be a JSON object. Lists are rejected.

Keys with non-null values are added or replaced. Keys set to null are removed.

If every metadata key is removed, SAPP returns {} for metadata.

JSONNull removes metadata keys, while non-null values add or replace integration-owned metadata.
{
  "metadata": {
    "erp_id": "erp_tenant_8841",
    "lifecycle": "production",
    "old_flag": null
  }
}

Error envelope

Authentication failures use the API key error envelope:

Validation errors on metadata patches identify the metadata field.

JSONUse the stable error code for application branching; the human-readable title and message can evolve.
{
  "status": "error",
  "error": {
    "title": "API key has expired",
    "message": "This API key has expired. Generate a new key in the management panel.",
    "code": "APIKEY:AUTH003"
  }
}

Support

Request Help

Open a Skyfallen ONE support request for your organisation and continue the conversation in Success Manager.

Open a request
English