Skip to main content

Build integrations · Public

CAS sign-in and session API

Sign users into your application with Skyfallen CAS, then read the current user, tenant, membership, or billing profile.

Breaking change — membership role field
POST /api/cas/membership no longer returns a human-readable role name in role. role is now the tenant role UUID (or null when no role is assigned). The display name is in role_name.
Clients that compared membership.role to strings such as "Member", "admin", or "owner" must switch to the UUID in role or the label in role_name. Keep using permissions for authorization checks.

Skyfallen CAS is an authorization-code sign-in flow for connected applications. The browser visits ONE to sign in and grant consent. Your server exchanges the returned code for a CAS session token, then calls IDMS CAS endpoints with that token.

HTTP requestExchange the one-time CAS code from your backend and keep the app secret away from browser JavaScript.
POST /api/cas/session HTTP/1.1
Host: idms.skyfallen.one
Content-Type: application/json
Accept: application/json

{
  "code": "018fd4f9-5c5b-7344-b4e1-d39c64d1770f",
  "secret": "cas_app_secret"
}

Prerequisites

An administrator registers a CAS application in ONE. Members need the cas:auth permission on the tenant they select during consent. Your app needs:

Setting Notes
App ID UUID used in the browser authorization URL.
Secret Plain secret shown only at creation. Store it server-side.
Redirect URL Exact callback URL that receives ?code=....
Code expiry Number of seconds an authorization code remains valid.
Session expiry Number of minutes a CAS session token remains valid.

Browser authorization

Send the user to the auth domain:

HTTP requestRedirect the browser here so ONE can sign the user in and send a one-time code back to your callback.
GET /authorise/cas/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: auth.skyfallen.one

When an enterprise tenant enables custom domain, the same path may be opened on that tenant's custom hostname instead. Sign-in and consent still run in the browser; the server-side code exchange remains on idms.skyfallen.one.

The user signs in, selects a tenant when needed, and grants consent. ONE creates a short-lived authorization code and redirects the browser back to your registered redirect URL.

If your redirect URL is:

https://app.example.net/skyfallen/callback

the browser returns to:

https://app.example.net/skyfallen/callback?code=018fd4f9-5c5b-7344-b4e1-d39c64d1770f

The code is single-use. Exchange it immediately from your backend.

Exchange the code

Call POST /api/cas/session from your backend. Never send the app secret from browser JavaScript.

Invalid or expired codes return:

Invalid secrets return CAS:AUTH002.

JSONUse the stable error code for application branching; the human-readable title and message can evolve.
{
  "status": "error",
  "error": {
    "title": "Code is invalid",
    "message": "The code provided is either not valid or has expired. Please try again with a new code.",
    "code": "CAS:AUTH001"
  }
}

Read the signed-in user

All other CAS endpoints require a session token in the JSON body.

HTTP requestSend the CAS session token in the body when reading the current user, tenant, membership, or billing resource.
POST /api/cas/user HTTP/1.1
Host: idms.skyfallen.one
Content-Type: application/json
Accept: application/json

{
  "token": "018fd4fb-8f08-788e-9746-b49af3be8110"
}
JSONRepresentative JSON response; production objects can include more fields depending on the endpoint and privileges.
{
  "status": "success",
  "user": {
    "id": "018fd4c0-e2da-7c7d-8b8e-0f033193b383",
    "first_name": "Mavi",
    "last_name": "Gökyüzü",
    "email": "[email protected]"
  }
}
Method Path Response
POST /api/cas/session token.value, token.renew_token, and Unix token.expiry.
POST /api/cas/user The authenticated user for the session tenant.
POST /api/cas/tenant The tenant selected during consent.
POST /api/cas/membership Role UUID (role), role display name (role_name), and comma-separated permission names.
POST /api/cas/billing Billing address, billing email, and billing phone for the tenant.
POST /api/cas/account-delete Sends an account deletion link when self deletion is allowed.

Membership response

role is the tenant role UUID, or null when no role is assigned. role_name is the display name, or null when no role is assigned. Permission names still drive authorization checks.

HTTP requestSend the CAS session token in the body when reading the current user, tenant, membership, or billing resource.
POST /api/cas/membership HTTP/1.1
Host: idms.skyfallen.one
Content-Type: application/json
Accept: application/json

{
  "token": "018fd4fb-8f08-788e-9746-b49af3be8110"
}

Tenant and membership errors

If the user no longer has the tenant membership tied to the CAS session, ONE deletes the session and returns a tenant error.

Code Typical action
CAS:TENANT001 Clear your local session and restart authorization before reading user data.
CAS:TENANT002 Clear your local session and restart authorization before reading tenant or billing data.
CAS:TENANT003 Clear your local session and restart authorization before reading membership data.

Security notes

Use HTTPS on your redirect URL.

Store the CAS token server-side or in a secure, HTTP-only session cookie owned by your application.

Respect token.expiry. When the token expires, clear local state and send the user through authorization again.

If you use the optional state query parameter on the browser authorization URL, ONE preserves it through the pending application flow.

Support

Request Help

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

Open a request
English