Auth

Auth signs in the people who use your app. They are end users: a record in your environment, never a Sylphx account. Auth holds their passwords (hashed and checked against breached passwords), their sessions and their sign-in history, so your app does not.

You work with Auth in two places.

• Your server manages end users and their sessions through the one API at https://api.sylphx.com, with your secret key.
• Your pages sign users in through the client API at https://api.sylphx.com/v1/client, with a publishable key that is safe to ship in a browser.

#What is served

Every provider returns to one callback: https://api.sylphx.com/v1/oidc/callback. When you bring your own Google, GitHub or Apple client, register exactly that URL with the provider.

#The two keys

Publishable key

sylphx_pk_live_… or sylphx_pk_test_…, scope auth:public. For the client API. Public by design.

Secret key

sylphx_sk_…, scope auth:read and auth:write. For end_users and sessions. Server only.

The platform delivers SYLPHX_PUBLISHABLE_KEY to every environment's services at runtime, not at build time. Read it on your server and pass it to the page.

#How a sign-in reaches your app

1. The page reads GET /v1/client/config?publishable_key=…: the enabled methods, the social providers with their start_url, and your branding.
2. The user signs in. Password: POST /v1/client/sign-in/password. Social: send the browser to /v1/client/oauth/{provider}/start?publishable_key=…&redirect_url=….
3. With the default session_mode: "server", the page receives a one-time ticket (two minutes, one use), as auth_ticket on your redirect_url or in the password answer. Your server redeems it with POST /v1/client/tickets:redeem and keeps the session in an HttpOnly cookie. No bearer token is ever readable by page script. Apps with no backend use session_mode: "browser" and hold the session bearer.
4. GET /v1/client/session returns the current session and user, and POST /v1/client/sign-out ends it.

An error is a JSON object with a stable code: invalid_request, unauthorized, mfa_required, forbidden, not_found, conflict, locked_out (with Retry-After), rate_limited, internal and store_unavailable. mfa_required means the user has a second factor: send it as factor_proofs on the next password sign-in. Sign-up always answers 202 {"accepted": true}, whether or not the email already has an account.

#Manage end users from your server

sylphx auth end-users list orgs/acme/projects/shop/envs/production
sylphx auth sessions list orgs/acme/projects/shop/envs/production/end_users/<user>
sylphx auth end-users revoke-sessions orgs/acme/projects/shop/envs/production/end_users/<user>

Deleting an end user is revocation: every session ends and new sign-ins are refused. The quickstart creates, reads and deletes one.

#Sign in a CLI or an agent: the device flow

For a program with no browser form, Auth serves the OAuth device grant (RFC 8628). An OAuth client that allows the device grant calls POST https://api.sylphx.com/v1/oauth/device_authorization and receives a device_code, a short user_code and a verification_uri: the Account Portal's /device page. The user opens …/device?user_code=ABCD-EFGH (?code= works too) or opens /device and types the code, signs in, and approves or denies. The program polls POST /v1/oauth/token with the device grant until it is approved. sylphx login uses the same pattern against sylphx.com/device. The oauth_clients collection in the API reference is not routed on api.sylphx.com: write to hi@sylphx.com and we register a client for your environment.