Flitt ID — OpenID Connect API¶
Flitt ID is a digital identification service for companies, built for B2B. It lets your platform identify a business customer and receive the company's registration data, already verified by Flitt, instead of collecting forms and documents. The customer signs in with their Flitt account, selects one of their companies and agrees to share its details. Your platform receives the company's legal name, registration number, VAT number and country, along with the director's name and work contacts.
Overview¶
Technically, Flitt ID is an OpenID Connect provider at portal.flitt.com. A partner application signs in on behalf of a Flitt portal user and receives the details of the company the user selected at sign-in, and of its director.
Typical scenario: an accounting service, CRM or marketplace connects a customer's company without manual entry of details. The user signs in to the portal as usual (password, MFA), selects one of their companies and grants access. The application receives:
- ID token — who signed in and how;
- access token — to request details of the company, its director and the user's email from UserInfo;
- refresh token — if
offline_accessis requested.
One flow is supported — Authorization Code with PKCE (OpenID Connect Core 1.0, RFC 6749, RFC 7636). CIBA, Implicit, Hybrid and Resource Owner Password Credentials are not supported.
One connection = one user + one application + one company. To obtain another company's details, the application starts sign-in again, and the user selects another company.
Environments and discovery¶
Get all endpoint URLs from the discovery document, not from code: paths may change, but the issuer does not.
| Environment | Issuer | Discovery |
|---|---|---|
| Production | https://portal.flitt.com |
https://portal.flitt.com/.well-known/openid-configuration |
The response may be cached for the period in Cache-Control (5 minutes).
{
"issuer": "https://portal.flitt.com",
"authorization_endpoint": "https://portal.flitt.com/oauth2/authorize",
"token_endpoint": "https://portal.flitt.com/oauth2/token",
"userinfo_endpoint": "https://portal.flitt.com/oauth2/userinfo",
"jwks_uri": "https://portal.flitt.com/oauth2/jwks",
"revocation_endpoint": "https://portal.flitt.com/oauth2/revoke",
"end_session_endpoint": "https://portal.flitt.com/oauth2/logout",
"scopes_supported": ["openid", "email", "company", "offline_access"],
"response_types_supported": ["code"],
"response_modes_supported": ["query"],
"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"],
"token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "private_key_jwt", "none"],
"token_endpoint_auth_signing_alg_values_supported": ["RS256", "ES256"],
"revocation_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "private_key_jwt", "none"],
"subject_types_supported": ["public"],
"id_token_signing_alg_values_supported": ["RS256"],
"claims_supported": ["sub", "iss", "aud", "exp", "iat", "auth_time", "nonce", "acr", "amr", "sid", "email", "email_verified", "company", "director"],
"claims_parameter_supported": false,
"request_parameter_supported": false,
"request_uri_parameter_supported": false,
"prompt_values_supported": ["none", "login", "consent", "select_account"],
"ui_locales_supported": ["en", "ka", "uk", "ru"],
"acr_values_supported": ["urn:flitt:acr:mfa"],
"authorization_response_iss_parameter_supported": true
}
JWKS (jwks_uri) — public ID token signing keys in RFC 7517 format. The set always contains two or three keys (current, next, previous): select the key by kid from the token header; an unknown kid means you should fetch JWKS once again.
{
"keys": [
{"kty": "RSA", "use": "sig", "alg": "RS256", "kid": "2026-10", "n": "0vx7agoebGcQSuu...", "e": "AQAB"}
]
}
Client registration¶
Register the application in the Flitt portal: Settings → Integrations → OAuth applications. Registration provides a client_id; confidential clients also receive a client_secret (shown once).
| Field | Required | What to specify |
|---|---|---|
| Name and logo | yes | Shown to the user on the consent screen |
redirect_uris |
yes | Full URLs, https only. Compared character by character |
post_logout_redirect_uris |
no | Where to return the user after logout |
| Client type | yes | confidential (server) or public (SPA, mobile application) |
token_endpoint_auth_method |
yes | See the table below |
jwks_uri or jwks |
for private_key_jwt |
Client's public keys |
| Allowed scopes | yes | A subset from the “Scopes and claims” section |
Client authentication at token and revoke:
| Method | For whom | How it is sent |
|---|---|---|
private_key_jwt |
Recommended for servers | client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer + client_assertion (JWT, RS256/ES256, aud = token_endpoint, unique jti, exp ≤ 5 min) |
client_secret_basic |
Servers | Authorization: Basic base64(client_id:client_secret) |
client_secret_post |
Servers | client_id and client_secret in the form body |
none |
Public clients | Only client_id; code protection — PKCE |
Dynamic client registration (RFC 7591) is not supported: each application is manually reviewed by Flitt before going to production.
Authorization Code + PKCE¶
The user selects a company in the portal between sign-in and consent; the application receives its details in UserInfo via the company scope.
sequenceDiagram
participant App as Application
participant Browser
participant Portal as Flitt Portal
Browser->>App: 1. “Sign in with Flitt”
App-->>Portal: 2. 302 → /oauth2/authorize: PKCE, state, nonce, scope
Note over Portal: 3. Sign-in: password and MFA
rect rgba(66, 133, 244, 0.15)
Browser-->Portal: portal screens
Note over Portal: 4. Company selection
end
Note over Portal: 5. Consent to scopes
Portal-->>App: 6. 302 → redirect_uri: code, state, iss
App->>Portal: 7. POST /oauth2/token: code + code_verifier
Portal->>App: 8. id_token, access_token, refresh_token
App->>Portal: 9. GET /oauth2/userinfo, Bearer access_token
Portal->>App: 10. Company and director details, and user email
Authorization Code + PKCE · 10 steps, company selection — step 4. Solid lines — server ↔ server; dashed lines — via browser (302 redirect).
Dashed lines — browser redirects: the code passes through the browser; tokens — only between servers.
The portal handles steps 3–5 itself:
- Sign-in. If a portal session exists and
promptdoes not require a new sign-in, this step is skipped. Users with MFA enabled enter an OTP; without a verified email, OAuth sign-in is not possible. - Company selection. Only companies where the user has editing rights are listed; companies cannot be connected with view-only rights. Search by name; if there is only one company, it is preselected, but the step is not skipped. No step if
companywas not requested. - Consent. The user sees the application's name and logo, the
redirect_uridomain and the text “You agree to share the following data with ‹application name›”, listing specific values for the selected company — exactly what UserInfo will return (table below). Consent is saved for the application + company pair and is shown again if the application requests new scopes.
| Scope | Consent screen text |
|---|---|
email |
Your email: nino@shop.example |
company |
Company details for Shop Example LLC: name, registration number, VAT number, country |
company |
Director Giorgi Kapanadze: full name, work email and work phone number |
offline_access |
Access remains until you revoke it (up to 30 days of inactivity) |
Endpoint reference¶
All endpoints require TLS 1.2+. Responses from token, userinfo and revoke include Cache-Control: no-store.
GET /oauth2/authorize¶
Redirect the user's browser. The portal shows sign-in, company selection and consent, then returns the user to redirect_uri.
| Parameter | Req. | Description |
|---|---|---|
response_type |
yes | Only code |
client_id |
yes | Client identifier |
redirect_uri |
yes | Exactly as registered |
scope |
yes | Space-separated, must include openid |
state |
yes | Random value, up to 1024 characters, returned unchanged |
nonce |
yes | Random value, included in the ID token |
code_challenge |
yes | BASE64URL(SHA256(code_verifier)), 43–128 characters |
code_challenge_method |
yes | Only S256 |
prompt |
no | login — sign in again; consent — show consent; select_account — show company selection, even if consent already exists; none — no UI, otherwise an error |
login_hint |
no | Portal user's email |
ui_locales |
no | en, ka, uk, ru |
max_age |
no | Maximum sign-in age in seconds; older — sign in again |
acr_values |
no | urn:flitt:acr:mfa — require sign-in with MFA |
Success — 302 to redirect_uri:
https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj&iss=https%3A%2F%2Fportal.flitt.com
Error — 302 to redirect_uri with error, error_description, state, iss. If client_id or redirect_uri is invalid, the user sees the portal's error page and nothing is returned to the application. The code is valid for 5 minutes and can be exchanged once.
POST /oauth2/token¶
Content-Type: application/x-www-form-urlencoded. Code exchange:
| Parameter | Value |
|---|---|
grant_type |
authorization_code |
code |
Code from the redirect |
redirect_uri |
Same as in the authorization request |
code_verifier |
Original PKCE value |
client_id + authentication |
According to the client's method |
Refresh: grant_type=refresh_token, refresh_token, client authentication, optional scope (narrowing only). The refresh token is single-use: a new one is returned; reusing the old one revokes the entire grant.
{
"access_token": "Hx3v1oQ8sZ...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA...",
"scope": "openid email company offline_access",
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIwMjYtMTAifQ..."
}
GET | POST /oauth2/userinfo¶
Authorization: Bearer <access_token>. Returns JSON with claims for the granted scopes (see “Scopes and claims”). Invalid token — 401 with WWW-Authenticate: Bearer error="invalid_token".
GET /oauth2/jwks¶
Public signing keys, no authentication. Cache-Control: max-age=3600.
POST /oauth2/revoke¶
RFC 7009: token + client authentication. Revoking a refresh token revokes the entire grant, including access tokens. Always 200 {}, even for an unknown token.
GET /oauth2/logout¶
RP-Initiated Logout 1.0: id_token_hint, post_logout_redirect_uri (registered), state. Ends the portal session after user confirmation. The grant and application tokens are not revoked — use revoke for that.
Scopes and claims¶
openid is required; other scopes must be allowed for the client at registration. The user sees each scope on the consent screen as a separate line.
| Scope | Claims | Returned in |
|---|---|---|
openid |
sub, auth_time, acr, amr |
ID token; sub — also in UserInfo |
email |
email, email_verified — email of the user who signed in |
UserInfo |
company |
company — selected company's details; director — its director |
UserInfo |
offline_access |
— | A refresh token is issued |
Company selection. If company is requested, the portal shows companies where the user has editing rights, and the user selects exactly one. The selection is fixed in the connection and does not change on token refresh. Permissions are checked on every token exchange and refresh and on every UserInfo request: if editing rights are removed, the connection is revoked.
Example UserInfo response for openid email company:
{
"sub": "u_8Kq2mZ4tR1vX",
"email": "nino@shop.example",
"email_verified": true,
"director": {
"name": "Giorgi Kapanadze",
"given_name": "Giorgi",
"family_name": "Kapanadze",
"email": "g.kapanadze@shop.example",
"phone_number": "+995322123456"
},
"company": {
"legal_name": "Shop Example LLC",
"registration_number": "405123456",
"vat_number": "405123456",
"country": "GE"
}
}
| Claim | Type and format | Description |
|---|---|---|
sub |
string, up to 255 | Opaque, persistent user identifier, required by OpenID Connect |
email, email_verified |
string, boolean | Email of the user who signed in; email_verified is always true |
amr |
string[], RFC 8176 | pwd, otp, fed (sign-in via Google) |
acr |
string | urn:flitt:acr:mfa, if signed in with MFA |
director.name, given_name, middle_name, family_name |
string | Company director's full name from Flitt verification data |
director.email |
string | Director's work email |
director.phone_number |
string, E.164 | Director's work phone number |
company.legal_name |
string | Legal name of the legal entity or sole proprietor |
company.registration_number |
string | Registration number, without spaces or separators; use it to link the company to your system |
company.vat_number |
string | VAT number, if any |
company.country |
string, ISO 3166-1 alpha-2 | Country of registration |
email and email_verified — standard OIDC Core §5.1 claims. director and company — private Flitt claims (§5.1.2), declared in claims_supported; the director's fields use standard person claim names and formats. If no director is specified in the company data, the director claim is omitted. Internal Flitt identifiers, documents and the director's personal contact details are not disclosed. Empty values are omitted, not returned as "" or null. The claims parameter is not supported: claims are determined only by scopes.
Tokens¶
ID token — a signed JWT; access and refresh tokens — opaque strings; do not attempt to parse them.
| Token | Format | Lifetime | Notes |
|---|---|---|---|
| Authorization code | opaque string | 5 min | Single-use, bound to client_id, redirect_uri and PKCE |
| ID token | JWT, RS256 | 10 min | For authentication only, not for API calls |
| Access token | opaque string | 1 hour | Authorization: Bearer for UserInfo and API |
| Refresh token | opaque string | 30 days | Only with offline_access; single-use, rotated on every exchange |
Example ID token payload:
{
"iss": "https://portal.flitt.com",
"sub": "u_8Kq2mZ4tR1vX",
"aud": "cl_7f3e2b9a4c",
"exp": 1793112600,
"iat": 1793112000,
"auth_time": 1793111940,
"nonce": "n-0S6_WzA2Mj",
"acr": "urn:flitt:acr:mfa",
"amr": ["pwd", "otp"],
"sid": "s_2Pq9wL",
"at_hash": "77QmUPtjPfzWtF2AnpK9RQ"
}
Application-side ID token validation (OIDC Core §3.1.3.7):
- Header
alg=RS256; key selected from JWKS bykid; signature valid. issmatches the discovery issuer character by character.audcontains yourclient_id.expis in the future,iatis no older than 10 minutes (allowed clock skew — 60 s).noncematches the value sent in the authorization request.- If
acr_valuesormax_agewas sent — checkacrandauth_time. at_hashmatches the received access token.
In a refresh_token response, a new ID token is issued without nonce, with the same sub and auth_time.
Errors¶
Errors follow RFC 6749 §4.1.2.1, §5.2 and OIDC Core §3.1.2.6: error is a machine-readable code; error_description is text for logs, not for display to the user.
| Code | Where | HTTP | When |
|---|---|---|---|
invalid_request |
authorize, token | 302 / 400 | Required parameter missing, parameter duplicated, no PKCE |
unsupported_response_type |
authorize | 302 | response_type ≠ code |
invalid_scope |
authorize, token | 302 / 400 | Missing openid or scope not allowed for the client |
access_denied |
authorize | 302 | User denied access or has no editing rights for any company |
login_required |
authorize | 302 | prompt=none, but the user is not signed in |
consent_required |
authorize | 302 | prompt=none, but no consent |
account_selection_required |
authorize | 302 | prompt=none, but no company was previously selected |
temporarily_unavailable |
authorize | 302 | Rate limit exceeded or service failure |
invalid_client |
token, revoke | 401 | Invalid client authentication |
invalid_grant |
token | 400 | Code expired or already used, PKCE mismatch, different redirect_uri, refresh revoked or reused |
unauthorized_client |
token | 400 | Client not allowed to use this grant_type |
unsupported_grant_type |
token | 400 | grant_type is not supported |
invalid_token |
userinfo | 401 | Access token expired, revoked, or the user's rights to edit the company were removed |
insufficient_scope |
userinfo | 403 | Token lacks openid |
Example token endpoint response:
{"error": "invalid_grant", "error_description": "authorization code expired or already used"}
For 429 from any endpoint, do not retry before the time specified in the header Retry-After.
Security requirements¶
The integration must comply with OAuth 2.0 Security Best Current Practice (RFC 9700); violating any item below is grounds for disabling the client.
- PKCE is required for all clients, including confidential clients: a new
code_verifier(32+ random bytes) for each sign-in. stateandnonce— random, bound to the browser session, checked before any response processing.- Compare
issin the authorization response (RFC 9207) with the issuer — this prevents mix-up attacks when working with multiple providers. redirect_uri— registered URLs only,https, with no open redirects on the callback page.- Secrets and keys (
client_secret, the private key forprivate_key_jwt) are stored only on the server; for SPAs and mobile applications, use a public client. - Tokens must not appear in URLs, logs or analytics. The refresh token is stored encrypted.
- Refresh token rotation: after each exchange, the old token is invalid. Concurrent refreshes from multiple processes will revoke the grant — serialize them.
- Revoke the grant (
/oauth2/revokewith the refresh token) when the user disconnects the integration in your application. - Secret rotation: the portal allows two active
client_secretvalues; issue a new one, deploy it, then revoke the old one.
The user sees all granted access in the portal (Profile → Connected applications) and can revoke any of it — the application must handle invalid_grant and invalid_token correctly and prompt the user to sign in again.
Integration examples¶
A complete flow for a confidential client using client_secret_basic. In production code, use a certified OIDC library for your language (see the list from the OpenID Foundation).
1. Prepare PKCE, state, nonce and redirect the user
session_start();
function base64url(string $bytes): string
{
return rtrim(strtr(base64_encode($bytes), '+/', '-_'), '=');
}
$verifier = base64url(random_bytes(48));
$challenge = base64url(hash('sha256', $verifier, true));
$state = base64url(random_bytes(24));
$nonce = base64url(random_bytes(24));
$_SESSION['verifier'] = $verifier; // server-side session
$_SESSION['state'] = $state;
$_SESSION['nonce'] = $nonce;
$url = 'https://portal.flitt.com/oauth2/authorize?' . http_build_query([
'response_type' => 'code',
'client_id' => 'cl_7f3e2b9a4c',
'redirect_uri' => 'https://app.example.com/callback',
'scope' => 'openid email company offline_access',
'state' => $state,
'nonce' => $nonce,
'code_challenge' => $challenge,
'code_challenge_method' => 'S256',
'ui_locales' => 'ka',
]);
using System.Security.Cryptography;
using System.Text;
using Microsoft.AspNetCore.WebUtilities;
var verifier = WebEncoders.Base64UrlEncode(RandomNumberGenerator.GetBytes(48));
var challenge = WebEncoders.Base64UrlEncode(SHA256.HashData(Encoding.ASCII.GetBytes(verifier)));
var state = WebEncoders.Base64UrlEncode(RandomNumberGenerator.GetBytes(24));
var nonce = WebEncoders.Base64UrlEncode(RandomNumberGenerator.GetBytes(24));
HttpContext.Session.SetString("verifier", verifier); // server-side session
HttpContext.Session.SetString("state", state);
HttpContext.Session.SetString("nonce", nonce);
var url = QueryHelpers.AddQueryString("https://portal.flitt.com/oauth2/authorize", new Dictionary<string, string?>
{
["response_type"] = "code",
["client_id"] = "cl_7f3e2b9a4c",
["redirect_uri"] = "https://app.example.com/callback",
["scope"] = "openid email company offline_access",
["state"] = state,
["nonce"] = nonce,
["code_challenge"] = challenge,
["code_challenge_method"] = "S256",
["ui_locales"] = "ka",
});
const crypto = require('crypto')
const verifier = crypto.randomBytes(48).toString('base64url')
const challenge = crypto.createHash('sha256').update(verifier).digest('base64url')
const state = crypto.randomBytes(24).toString('base64url')
const nonce = crypto.randomBytes(24).toString('base64url')
Object.assign(req.session, { verifier, state, nonce }) // server-side session
const url = 'https://portal.flitt.com/oauth2/authorize?' + new URLSearchParams({
response_type: 'code',
client_id: 'cl_7f3e2b9a4c',
redirect_uri: 'https://app.example.com/callback',
scope: 'openid email company offline_access',
state,
nonce,
code_challenge: challenge,
code_challenge_method: 'S256',
ui_locales: 'ka'
})
import base64, hashlib, secrets
from urllib.parse import urlencode
verifier = secrets.token_urlsafe(48)
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
state, nonce = secrets.token_urlsafe(24), secrets.token_urlsafe(24)
session.update(verifier=verifier, state=state, nonce=nonce) # server-side session
url = "https://portal.flitt.com/oauth2/authorize?" + urlencode({
"response_type": "code",
"client_id": "cl_7f3e2b9a4c",
"redirect_uri": "https://app.example.com/callback",
"scope": "openid email company offline_access",
"state": state,
"nonce": nonce,
"code_challenge": challenge,
"code_challenge_method": "S256",
"ui_locales": "ka",
})
2. Handle the callback: check state and iss; on error — show the error and stop.
3. Exchange the code for tokens
curl -s https://portal.flitt.com/oauth2/token \
-u 'cl_7f3e2b9a4c:CLIENT_SECRET' \
-d grant_type=authorization_code \
-d code=SplxlOBeZQQYbYS6WxSbIA \
-d redirect_uri=https://app.example.com/callback \
-d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
4. Validate the ID token (see “Tokens”) and link sub to the user in your system.
5. Get company and director details; link the company by company.registration_number
curl -s https://portal.flitt.com/oauth2/userinfo \
-H 'Authorization: Bearer Hx3v1oQ8sZ...'
6. Refresh tokens before the access token expires and save the new refresh token
curl -s https://portal.flitt.com/oauth2/token \
-u 'cl_7f3e2b9a4c:CLIENT_SECRET' \
-d grant_type=refresh_token \
-d refresh_token=tGzv3JOkF0XG5Qx2TlKWIA...
7. Disconnect the integration
curl -s https://portal.flitt.com/oauth2/revoke \
-u 'cl_7f3e2b9a4c:CLIENT_SECRET' \
-d token=tGzv3JOkF0XG5Qx2TlKWIA... -d token_type_hint=refresh_token