FoxShard Identity, Sign-in and identity API
Sign people in to the applications you build, on your own screens or ours
FoxShard Identity signs people in to your applications and issues the tokens your APIs check. People sign in with a password, a code sent by email or SMS, an authenticator app, or a Google, Facebook, Telegram, LinkedIn, GitHub or X account.
- OAuth 2.0 and OpenID Connect
- Sign-in API for your own screens
- Authenticator apps and codes
- Six social sign-in providers
Request
POST /oauth2/authorize-challenge
Authorization: Basic bXktYXBw…
Content-Type: application/x-www-form-urlencoded
X-End-User-IP: 203.0.113.7
response_type=code
&scope=openid%20profile
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256
&username=alice%40example.com
&password=…
Response
{
"authorization_code": "Zq3Lw0nRk8Yd…",
"known_device": "n4Fq7TzKc2Wb…"
}
Who it is for
-
Application developers
Standard OAuth 2.0 and OpenID Connect flows with PKCE, and access tokens that say who signed in and what they may do in your API.
-
Teams with their own screens
Keep people on your own sign-in screens: your server posts what they typed and gets the same tokens a browser sign-in gives.
-
Security leads
Authenticator apps, refresh tokens that rotate, limits on guessing passwords and codes, and an audit trail that is only ever added to.
-
Administrators
One dashboard to register applications, give and take back roles, reset two-step verification and suspend an account.
How it works
-
Send what they typed
Your server posts the username, the password and a PKCE challenge to the sign-in API, with its client secret and the person's IP address.
-
Ask for the next step
If the account has an authenticator app or needs an emailed code, the answer asks for it. Your screen shows a code field and your server sends the code.
-
Get the authorisation code
Once every step is done, the answer holds an authorisation code, and a known-device value to keep on the person's device for their next sign-in.
-
Exchange it for tokens
Your server swaps the code and its PKCE verifier at the token endpoint for an access token, a refresh token and an ID token.
-
Refresh and sign out
Each refresh hands out a new refresh token. To sign the person out, your server revokes the refresh token and forgets the tokens.
What it does
-
OAuth 2.0 and OpenID Connect
The authorisation code flow with PKCE, ID tokens, refresh tokens and revocation, and discovery at
/..well-known/ openid-configuration -
Sign-in on your own screens
Your server posts what people type to
POST /, following the IETF draft for first-party apps, and gets an authorisation code or the next step.oauth2/ authorize-challenge -
Passwords and one-time codes
People sign in with a username, email address or phone number and a password, or with a six-digit code sent to an email address or phone number they have verified.
-
Two-step verification
Authenticator apps, several to an account, and single-use recovery codes. Adding an app takes a sign-in from the last 15 minutes.
-
Social sign-in
Google, Facebook, Telegram, LinkedIn, GitHub and X. The first sign-in creates the account and links it, and every later one finds the account by that link.
-
Roles and permissions in the token
Each application has its own roles and permissions. The access token names its API in
audand carries the person'srolesandpermissionsthere. -
Rotating tokens and keys
Every refresh hands out a new refresh token, and one used twice ends the sign-in. Signing keys rotate without a restart, and the previous public key stays published.
-
Administrators' dashboard
Register applications, give and take back roles, reset two-step verification or suspend an account, which signs it out everywhere. The management API grants roles from code.
Questions
Can we keep people on our own sign-in screens?
Yes, for your own applications. An administrator turns it on for a client that has a secret. Your server posts what the person typed to POST / and gets an authorisation code, or a request for the next step, such as an authenticator code. The tokens are the same as after a browser sign-in.
Which ways of signing in does it support?
A password with a username, email address or phone number, a one-time code by email or SMS, an authenticator app or recovery code as the second step, and Google, Facebook, Telegram, LinkedIn, GitHub or X. Signing up, resetting a password, social sign-in and setting up an app happen on Identity's own pages.
How does our API know what someone may do?
The access token is a signed JWT. Its aud names your API, client_id names the application, and roles and permissions list what the person holds in that API. A change to their roles reaches their next token. Your API checks the signature against the keys published at /.
Can a browser or phone app call the sign-in API itself?
No. The API takes no client without its secret, so it is called by a server you run. A browser or phone app talks to that server, which keeps the tokens in its own session and gives the browser an HttpOnly cookie. The secret and the tokens never reach the browser.
What stops someone guessing passwords or codes?
Sign-in steps are limited for each person's IP address, and after too many wrong passwords an account's password is not checked for a while. Codes have their own limits for each email address, phone number and known device, so a stranger cannot use up the owner's codes. An unknown account gets the same answer as a wrong password.
Can applications from other companies use it?
Yes, through Identity's own sign-in pages. People signing in to an application that is not marked as trusted are asked first whether it may act in their name. Sign-in on your own screens is for your own applications only, because they see people's passwords.
Talk to us about Identity
Tell us what you are building, and we will set you up with keys to try it.