# FoxShard Identity: Sign people in to the applications you build, on your own screens or ours

*Web page: https://foxshard.com/solutions/identity. Updated 2026-11-17*

*Sign-in and identity API, by FoxShard*

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

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

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

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

## A request to the API

Sign a person in with a password from your own server: the answer is an authorisation code to exchange for tokens.

```http
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=…
```

```json
{
  "authorization_code": "Zq3Lw0nRk8Yd…",
  "known_device": "n4Fq7TzKc2Wb…"
}
```

## 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 FoxShard Identity

Use the form at https://foxshard.com/contact?solution=identity. Email: support@foxshard.com.
