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

Talk to us about Identity See how it works

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…"
}
Sign a person in with a password from your own server: the answer is an authorisation code to exchange for tokens.

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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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 /oauth2/authorize-challenge, following the IETF draft for first-party apps, and gets an authorisation code or the next step.

  • 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 aud and carries the person's roles and permissions there.

  • 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 /oauth2/authorize-challenge 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 /oauth2/jwks.

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.

Send us a message