Skip to main content

Build integrations · Public

API overview

A map of ONE API surfaces — domains, authentication styles, response shapes, and habits that keep integrations safe.

Skyfallen ONE exposes identity APIs from the idms subdomain.

HTTP requestUse API key headers for SAPP and tenant signup calls, especially when the endpoint is a GET request.
GET /api/tenants 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

Domains

ONE uses separate subdomains for the product experience and the API surface.

Host Purpose
auth.skyfallen.one Browser sign-in, consent, passkeys, password reset, and CAS authorization.
idms.skyfallen.one API calls for tenant signup, CAS session exchange, CAS resource reads, SAPP reads, SAPP metadata updates, and trusted service lookups.
my.skyfallen.one User account and security settings.
iam.skyfallen.one Organisation administration, members, integrations, API keys, and subscriptions.
help.skyfallen.one Human documentation.

Enterprise tenants may also publish browser sign-in on an enabled custom hostname. Server-side API calls still use idms.skyfallen.one.

The API base URL is:

https://idms.skyfallen.one/api

API families

ONE has a few different API families because they serve different actors.

Family Primary actor Authentication Use it for
Tenant signup Approved partner or internal onboarding client API key headers Creating commercial or enterprise tenants from a controlled signup flow.
SAPP Provisioning and lifecycle systems API key headers Reading tenants, users, memberships, and patching integration metadata.
SAPP webhooks Receiving application HMAC signature Receiving account, tenant, membership, and metadata change events.
CAS Connected application backend Authorization code, app secret, session token Signing users in and reading the current user, tenant, membership, or billing profile.

Authentication styles

SAPP and tenant signup use API key credentials. Send credentials as headers, especially for GET requests.

CAS uses a browser authorization step first. Your server exchanges the returned authorization code and app secret for a session token, then sends that token in later CAS API bodies.

SAPP webhooks are different again. Skyfallen signs outbound webhook payloads with your subscription secret. Your receiver verifies the timestamp and signature before trusting the event.

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

Response envelopes

Provisioning APIs return a consistent success envelope:

JSONRepresentative JSON response; production objects can include more fields depending on the endpoint and privileges.
{
  "status": "success",
  "data": {}
}

API key authentication failures return an error envelope:

JSONUse the stable error code for application branching; the human-readable title and message can evolve.
{
  "status": "error",
  "error": {
    "title": "Client secret is invalid",
    "message": "The client secret provided is not valid.",
    "code": "APIKEY:AUTH004"
  }
}

CAS endpoints also use status, but many successful responses put the named resource at the top level:

JSONRepresentative JSON response; production objects can include more fields depending on the endpoint and privileges.
{
  "status": "success",
  "user": {
    "id": "018fd4c0-e2da-7c7d-8b8e-0f033193b383",
    "email": "[email protected]"
  }
}

Integration habits

Keep API credentials and CAS app secrets on the server. Do not ship them in browser code, mobile app bundles, or logs.

Treat all identifiers as strings. Many identifiers are UUID-style values, but membership IDs may not look the same as tenant and user IDs.

Prefer reconciliation after webhooks. Webhooks tell you what changed, but the read API is the source to call when your system needs the current full object.

Respect access boundaries. Some help pages are public today, but the document metadata already carries an access level and optional privilege list so sensitive operational pages can later be limited to signed-in users or privileged teams.

HTTP status codes

Most successful reads return 200. Tenant signup returns 201 when it creates the user, tenant, membership, and verification records.

Authentication and validation errors are returned as JSON. Read the error.code value first; it is more stable than prose.

Dates and nulls

Timestamps are ISO 8601 strings unless a field is explicitly a date, such as birthdate or date_established.

Empty metadata is returned as {}. Missing optional fields are commonly null.

Support

Request Help

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

Open a request
English