Skip to content

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_access is 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:

  1. Sign-in. If a portal session exists and prompt does 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.
  2. 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 company was not requested.
  3. Consent. The user sees the application's name and logo, the redirect_uri domain 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):

  1. Header alg = RS256; key selected from JWKS by kid; signature valid.
  2. iss matches the discovery issuer character by character.
  3. aud contains your client_id.
  4. exp is in the future, iat is no older than 10 minutes (allowed clock skew — 60 s).
  5. nonce matches the value sent in the authorization request.
  6. If acr_values or max_age was sent — check acr and auth_time.
  7. at_hash matches 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.
  • state and nonce — random, bound to the browser session, checked before any response processing.
  • Compare iss in 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 for private_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/revoke with the refresh token) when the user disconnects the integration in your application.
  • Secret rotation: the portal allows two active client_secret values; 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